module xdc.runtime.knl.Thread

Thread services. [EXPERIMENTAL]

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation

This module manages threads through a proxy which inherits from IThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]

XDCspec summary sourced in xdc/runtime/knl/Thread.xdc

module Thread { ...

// inherits xdc.runtime.IModule

instance: ...

C synopsis target-domain

#include <xdc/runtime/knl/Thread.h>

module-wide constants & types

#define Thread_GETPRI_FAILED// Status returned by getPri when an error occurs (Int)-2

#define Thread_INVALID_OS_PRIORITY// Invalid OS priority value (Int)0

typedef enum Thread_CompStatus// Status returned by compareOsPriorities when an error occurs {

Thread_CompStatus_ERROR,

Thread_CompStatus_LOWER,

Thread_CompStatus_EQUAL,

Thread_CompStatus_HIGHER

} Thread_CompStatus;

typedef enum Thread_Priority// Thread priorities which are mapped to OS specific value by Proxy {

Thread_Priority_INVALID,

Thread_Priority_LOWEST,

Thread_Priority_BELOW_NORMAL,

Thread_Priority_NORMAL,

Thread_Priority_ABOVE_NORMAL,

Thread_Priority_HIGHEST

} Thread_Priority;

typedef Void (*Thread_RunFxn// Typedef for thread function)(IArg);

typedef struct Thread_Stat// Struct to hold thread statistics from stat {

SizeT stackSize;

SizeT stackUsed;

} Thread_Stat;

module-wide config parameters

extern const Assert_Id Thread_A_zeroTimeout// Assert when timeout passed to sleep is zero;

extern const SizeT Thread_defaultStackSize// Default thread stack size;

module-wide functions

Int Thread_compareOsPriorities// Compare two os specific priority values and find out which one represents a higher priority( Int p1, Int p2, Error_Block *eb );

Thread_Handle Thread_self// Return the currently executing thread's handle( Error_Block *eb );

Bool Thread_sleep// Sleep for given number of microseconds( UInt timeout, Error_Block *eb );

Bool Thread_start// Start threads running( Error_Block *eb );

Bool Thread_yield// Yield the currently scheduled thread( Error_Block *eb );

module-wide built-ins

Types_ModuleId Thread_Module_id// Get this module's unique id( );

Bool Thread_Module_startupDone// Test if this module has completed startup( );

IHeap_Handle Thread_Module_heap// The heap from which this module allocates memory( );

Bool Thread_Module_hasMask// Test whether this module has a diagnostics mask( );

Bits16 Thread_Module_getMask// Returns the diagnostics mask for this module( );

Void Thread_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );

per-instance object types

typedef struct Thread_Object// Opaque internal representation of an instance object Thread_Object;

typedef Thread_Object *Thread_Handle// Client reference to an instance object;

typedef struct Thread_Struct// Opaque client structure large enough to hold an instance object Thread_Struct;

Thread_Handle Thread_handle// Convert this instance structure pointer into an instance handle( Thread_Struct *structP );

Thread_Struct *Thread_struct// Convert this instance handle into an instance structure pointer( Thread_Handle handle );

per-instance config parameters

typedef struct Thread_Params// Instance config-params structure {

IInstance_Params *instance;

IArg arg// Thread function argument. Default is 0;

Int osPriority// OS specific thread priority;

Thread_Priority priority// Specify the new thread's priority;

SizeT stackSize// Thread stack size;

Ptr tls// Thread local storage;

} Thread_Params;

Void Thread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation( Thread_Params *params );

per-instance creation

Thread_Handle Thread_create// Allocate and initialize a new instance object and return its handle( Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb );

Void Thread_construct// Initialize a new instance object inside the provided structure( Thread_Struct *structP, Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb );

per-instance deletion

Void Thread_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL( Thread_Handle *handleP );

Void Thread_destruct// Finalize the instance object inside the provided structure( Thread_Struct *structP );

per-instance functions

Ptr Thread_getOsHandle// Get the OS thread handle( Thread_Handle handle );

Int Thread_getOsPriority// Obtain a thread's OS specific priority( Thread_Handle handle, Error_Block *eb );

Thread_Priority Thread_getPriority// Obtain a thread's priority( Thread_Handle handle, Error_Block *eb );

Ptr Thread_getTls// Obtain a thread's local storage( Thread_Handle handle );

Bool Thread_join// Block calling thread until given thread terminates( Thread_Handle handle, Error_Block *eb );

Bool Thread_setOsPriority// Set a thread's priority( Thread_Handle handle, Int newPri, Error_Block *eb );

Bool Thread_setPriority// Set a thread's priority( Thread_Handle handle, Thread_Priority newPri, Error_Block *eb );

Void Thread_setTls// Change a thread's local storage( Thread_Handle handle, Ptr tls );

Bool Thread_stat// Get thread statistics( Thread_Handle handle, Thread_Stat *buf, Error_Block *eb );

per-instance built-ins

Int Thread_Object_count// The number of statically-created instance objects( );

Thread_Handle Thread_Object_get// The handle of the i-th statically-created instance object (array == NULL)( Thread_Object *array, Int i );

Thread_Handle Thread_Object_first// The handle of the first dynamically-created instance object, or NULL( );

Thread_Handle Thread_Object_next// The handle of the next dynamically-created instance object, or NULL( Thread_Handle handle );

IHeap_Handle Thread_Object_heap// The heap used to allocate dynamically-created instance objects( );

Types_Label *Thread_Handle_label// The label associated with this instance object( Thread_Handle handle, Types_Label *buf );

String Thread_Handle_name// The name of this instance object( Thread_Handle handle );

XDCscript usage meta-domain

var Thread = xdc.useModule('xdc.runtime.knl.Thread');

local proxy modules

Thread.Proxy// Proxy that needs to be bound to an OS specific delegate = IThreadSupport.Module null

Thread.Proxy.delegate$ = IThreadSupport.Module null

Thread.Proxy.abstractInstances$ = false

module-wide constants & types

const Thread.GETPRI_FAILED// Status returned by getPri when an error occurs = -2;

const Thread.INVALID_OS_PRIORITY// Invalid OS priority value = 0;

values of type Thread.CompStatus// Status returned by compareOsPriorities when an error occurs

const Thread.CompStatus_ERROR;

const Thread.CompStatus_LOWER;

const Thread.CompStatus_EQUAL;

const Thread.CompStatus_HIGHER;

values of type Thread.Priority// Thread priorities which are mapped to OS specific value by Proxy

const Thread.Priority_INVALID;

const Thread.Priority_LOWEST;

const Thread.Priority_BELOW_NORMAL;

const Thread.Priority_NORMAL;

const Thread.Priority_ABOVE_NORMAL;

const Thread.Priority_HIGHEST;

var obj = new Thread.Stat// Struct to hold thread statistics from stat;

obj.stackSize = SizeT ...

obj.stackUsed = SizeT ...

module-wide config parameters

Thread.A_zeroTimeout// Assert when timeout passed to sleep is zero = Assert.Desc {

msg: "A_zeroTimeout: Timeout value annot be zero"

};

Thread.defaultStackSize// Default thread stack size = SizeT 0;

Thread.common$// Common module configuration parameters = Types.Common$ undefined;

per-instance config parameters

var params = new Thread.Params// Instance config-params object;

params.arg// Thread function argument. Default is 0 = IArg 0;

params.osPriority// OS specific thread priority = Int Thread.INVALID_OS_PRIORITY;

params.priority// Specify the new thread's priority = Thread.Priority Thread.Priority_NORMAL;

params.stackSize// Thread stack size = SizeT 0;

params.tls// Thread local storage = Ptr null;

per-instance creation

var inst = Thread.create// Create an instance-object( Void(*)(IArg) fxn, params );

XDCspec declarations sourced in xdc/runtime/knl/Thread.xdc

package xdc.runtime.knl;

module Thread {

local proxy modules

proxy Proxy inherits IThreadSupport;

module-wide constants & types

const Int GETPRI_FAILED// Status returned by getPri when an error occurs = -2;

const Int INVALID_OS_PRIORITY// Invalid OS priority value = 0;

enum CompStatus// Status returned by compareOsPriorities when an error occurs {

CompStatus_ERROR,

CompStatus_LOWER,

CompStatus_EQUAL,

CompStatus_HIGHER

};

enum Priority// Thread priorities which are mapped to OS specific value by Proxy {

Priority_INVALID,

Priority_LOWEST,

Priority_BELOW_NORMAL,

Priority_NORMAL,

Priority_ABOVE_NORMAL,

Priority_HIGHEST

};

typedef Void (*RunFxn// Typedef for thread function)(IArg);

struct Stat// Struct to hold thread statistics from stat {

SizeT stackSize;

SizeT stackUsed;

};

module-wide config parameters

config Assert.Id A_zeroTimeout// Assert when timeout passed to sleep is zero = {

msg: "A_zeroTimeout: Timeout value annot be zero"

};

config SizeT defaultStackSize// Default thread stack size = 0;

metaonly config Types.Common$ common$// Common module configuration parameters;

module-wide functions

Int compareOsPriorities// Compare two os specific priority values and find out which one represents a higher priority( Int p1, Int p2, Error.Block *eb );

Thread.Handle self// Return the currently executing thread's handle( Error.Block *eb );

Bool sleep// Sleep for given number of microseconds( UInt timeout, Error.Block *eb );

Bool start// Start threads running( Error.Block *eb );

Bool yield// Yield the currently scheduled thread( Error.Block *eb );

instance:

per-instance config parameters

config IArg arg// Thread function argument. Default is 0 = 0;

config Int osPriority// OS specific thread priority = Thread.INVALID_OS_PRIORITY;

config Thread.Priority priority// Specify the new thread's priority = Thread.Priority_NORMAL;

config SizeT stackSize// Thread stack size = 0;

config Ptr tls// Thread local storage = null;

per-instance creation

create// Create an instance-object( Thread.RunFxn fxn );

per-instance functions

Ptr getOsHandle// Get the OS thread handle( );

Int getOsPriority// Obtain a thread's OS specific priority( Error.Block *eb );

Thread.Priority getPriority// Obtain a thread's priority( Error.Block *eb );

Ptr getTls// Obtain a thread's local storage( );

Bool join// Block calling thread until given thread terminates( Error.Block *eb );

Bool setOsPriority// Set a thread's priority( Int newPri, Error.Block *eb );

Bool setPriority// Set a thread's priority( Thread.Priority newPri, Error.Block *eb );

Void setTls// Change a thread's local storage( Ptr tls );

Bool stat// Get thread statistics( Thread.Stat *buf, Error.Block *eb );

}

DETAILS

Here is an example showing how the proxy is bound to a BIOS 6.x specific delegate.

var Thread = xdc.useModule('xdc.runtime.knl.Thread'); Thread.Proxy = xdc.useModule('ti.sysbios.xdcruntime.ThreadSupport');

Typically a package containing the delegates has a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.

xdc.useModule('ti.sysbios.xdcruntime.Settings');

proxy Thread.Proxy