Thread services. [EXPERIMENTAL]
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');
proxy Thread.Proxy |
|
Proxy that needs to be bound to an OS specific delegate
XDCscript usage |
meta-domain |
// explicit access to the currently bound delegate module
Thread.Proxy.abstractInstances$ = false
// use indirect runtime function calls if true
const Thread.GETPRI_FAILED |
|
Status returned by getPri when an error occurs
XDCscript usage |
meta-domain |
const Thread.GETPRI_FAILED = -2;
#define Thread_GETPRI_FAILED (Int)-2
const Thread.INVALID_OS_PRIORITY |
|
Invalid OS priority value
XDCscript usage |
meta-domain |
const Thread.INVALID_OS_PRIORITY = 0;
#define Thread_INVALID_OS_PRIORITY (Int)0
enum Thread.CompStatus |
|
Status returned by compareOsPriorities when an error occurs
XDCscript usage |
meta-domain |
values of type Thread.CompStatus
const Thread.CompStatus_ERROR;
const Thread.CompStatus_LOWER;
const Thread.CompStatus_EQUAL;
const Thread.CompStatus_HIGHER;
typedef enum Thread_CompStatus {
Thread_CompStatus_ERROR,
Thread_CompStatus_LOWER,
Thread_CompStatus_EQUAL,
Thread_CompStatus_HIGHER
} Thread_CompStatus;
enum Thread.Priority |
|
Thread priorities which are mapped to OS specific value by Proxy
XDCscript usage |
meta-domain |
values of type Thread.Priority
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;
typedef enum Thread_Priority {
Thread_Priority_INVALID,
Thread_Priority_LOWEST,
Thread_Priority_BELOW_NORMAL,
Thread_Priority_NORMAL,
Thread_Priority_ABOVE_NORMAL,
Thread_Priority_HIGHEST
} Thread_Priority;
typedef Thread.RunFxn |
|
Typedef for thread function
typedef Void (*Thread_RunFxn)(IArg);
struct Thread.Stat |
|
Struct to hold thread statistics from stat
XDCscript usage |
meta-domain |
var obj = new Thread.Stat;
obj.stackSize = SizeT ...
obj.stackUsed = SizeT ...
typedef struct Thread_Stat {
SizeT stackSize;
SizeT stackUsed;
} Thread_Stat;
config Thread.A_zeroTimeout // module-wide |
|
Assert when timeout passed to sleep is zero
XDCscript usage |
meta-domain |
msg: "A_zeroTimeout: Timeout value annot be zero"
};
config Thread.defaultStackSize // module-wide |
|
Default thread stack size
XDCscript usage |
meta-domain |
Thread.defaultStackSize = SizeT 0;
extern const SizeT Thread_defaultStackSize;
metaonly config Thread.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
Thread.compareOsPriorities( ) // module-wide |
|
Compare two os specific priority values and find out which one
represents a higher priority
Int Thread_compareOsPriorities(
Int p1,
Int p2,
Error_Block *
eb );
ARGUMENTS
p1
priority one
p2
priority two
eb
Pointer to Error.Block
DETAILS
RETURNS
refer to description above
Thread.self( ) // module-wide |
|
Return the currently executing thread's handle
ARGUMENTS
eb
Pointer to Error.Block
RETURNS
Returns a handle to the currently executing thread.
If the current thread is the main thread, this function
returns NULL. NULL is also returned in case of error.
Thread.sleep( ) // module-wide |
|
Sleep for given number of microseconds
ARGUMENTS
timeout
timeout in microseconds
eb
Pointer to Error.Block
DETAILS
This function is gauranteed to sleep for at least as long as the
timeout value but the actual sleep time may be longer. NOTE:
The timeout value cannot be zero.
RETURNS
true for success; false for error
Thread.start( ) // module-wide |
|
Start threads running
ARGUMENTS
eb
Pointer to Error.Block
DETAILS
This function can be used to start all statically created threads,
and all threads created dynamically before this function is called.
Any thread created after this function is called, starts automatically.
(i.e., there is no need to call Thread_start() more than once).
RETURNS
true for success; false for error
Thread.yield( ) // module-wide |
|
Yield the currently scheduled thread
ARGUMENTS
eb
Pointer to Error.Block
RETURNS
true for success; false for error
module-wide built-ins |
|
// Get this module's unique id
Bool Thread_Module_startupDone( );
// Test if this module has completed startup
// The heap from which this module allocates memory
per-instance object types |
|
typedef struct Thread_Object Thread_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Thread_Struct Thread_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
per-instance config parameters |
|
XDCscript usage |
meta-domain |
var params = new Thread.Params;
// Instance config-params object
params.arg = IArg 0;
// Thread function argument. Default is 0
// OS specific thread priority
// Specify the new thread's priority
params.stackSize = SizeT 0;
// Thread stack size
params.tls = Ptr null;
// Thread local storage
typedef struct Thread_Params {
// Instance config-params structure
// Common per-instance configs
IArg arg;
// Thread function argument. Default is 0
Int osPriority;
// OS specific thread priority
// Specify the new thread's priority
SizeT stackSize;
// Thread stack size
Ptr tls;
// Thread local storage
} Thread_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Thread.arg // per-instance |
|
Thread function argument. Default is 0
XDCscript usage |
meta-domain |
var params = new Thread.Params;
...
params.arg = IArg 0;
config Thread.osPriority // per-instance |
|
OS specific thread priority
XDCscript usage |
meta-domain |
var params = new Thread.Params;
...
DETAILS
Used to specify an OS specific value for priority. If set this value
takes precedence over
priority.
config Thread.priority // per-instance |
|
Specify the new thread's priority
XDCscript usage |
meta-domain |
var params = new Thread.Params;
...
DETAILS
Thread defines several constants which allows applications to select
a priority in an OS independent way: Priority_LOWEST,
Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and
Priority_HIGHEST. These values get mapped to OS specific priorities
by the OS specific delegate.
config Thread.stackSize // per-instance |
|
Thread stack size
XDCscript usage |
meta-domain |
var params = new Thread.Params;
...
params.stackSize = SizeT 0;
DETAILS
The default value of 0 means that
defaultStackSize is used.
config Thread.tls // per-instance |
|
Thread local storage
XDCscript usage |
meta-domain |
var params = new Thread.Params;
...
params.tls = Ptr null;
DETAILS
User data associated with a thread. Must persist for the life of
the thread.
per-instance creation |
|
XDCscript usage |
meta-domain |
var params =
new Thread.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Thread.create( Void(*)(IArg) fxn, params );
// Create an instance-object
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
fxn
function for new thread to begin execution
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function spawns a new thread calling the function fxn.
per-instance deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Thread.getOsHandle( ) // per-instance |
|
Get the OS thread handle
ARGUMENTS
handle
handle of a previously-created Thread instance object
RETURNS
OS thread handle
Thread.getOsPriority( ) // per-instance |
|
Obtain a thread's OS specific priority
ARGUMENTS
handle
handle of a previously-created Thread instance object
eb
Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, the value returned
is the base priority of the thread.
RETURNS
thread priority in case of success; GETPRI_FAILED in
case of error;
Thread.getPriority( ) // per-instance |
|
Obtain a thread's priority
ARGUMENTS
handle
handle of a previously-created Thread instance object
eb
Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, this function
retrieves the base priority of the thread.
RETURNS
thread priority in case of success; PRIORITY_INVALID in
case of error;
Thread.getTls( ) // per-instance |
|
Obtain a thread's local storage
ARGUMENTS
handle
handle of a previously-created Thread instance object
RETURNS
null when tls has not been set.
Thread.join( ) // per-instance |
|
Block calling thread until given thread terminates
ARGUMENTS
handle
handle of a previously-created Thread instance object
eb
Pointer to Error.Block
DETAILS
Use this functions to ensure that a thread has terminated. It is OK to
call this function on a thread that has already terminated.
RETURNS
true for success; false for error
Thread.setOsPriority( ) // per-instance |
|
Set a thread's priority
ARGUMENTS
handle
handle of a previously-created Thread instance object
newPri
new thread priority
eb
Pointer to Error.Block
DETAILS
This API sets the base priority of the thread on OSes that
support dynamic priority boosting
RETURNS
true for success; false for error
Thread.setPriority( ) // per-instance |
|
Set a thread's priority
ARGUMENTS
handle
handle of a previously-created Thread instance object
newPri
new thread priority
eb
Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, this function
changes the base priority of the thread.
RETURNS
true for success; false for error
Thread.setTls( ) // per-instance |
|
Change a thread's local storage
ARGUMENTS
handle
handle of a previously-created Thread instance object
tls
tls
Thread.stat( ) // per-instance |
|
Get thread statistics
ARGUMENTS
handle
handle of a previously-created Thread instance object
buf
Pointer to Stat
eb
Pointer to Error.Block
RETURNS
true for success; false for failure
per-instance built-ins |
|
Int Thread_Object_count( );
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object