module xdc.runtime.knl.Thread
index URL

Thread services

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 ... ]
C synopsis target-domain sourced in xdc/runtime/knl/Thread.xdc
#include <xdc/runtime/knl/Thread.h>
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);
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);
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_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);
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);
Void
Thread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Thread_Params *params);
Thread_Handle 
Thread_self// Return the currently executing thread's 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_sleep// Sleep for given number of microseconds(UInt timeout, Error_Block *eb);
Bool 
Thread_start// Start threads running(Error_Block *eb);
Bool 
Thread_stat// Get thread statistics(Thread_Handle handle, Thread_Stat *buf, Error_Block *eb);
Bool 
Thread_yield// Yield the currently scheduled thread(Error_Block *eb);
Functions common to all target instances
Thread_handle// Convert this instance structure pointer into an instance handle, Thread_Handle_label// The label associated with this instance object, Thread_Handle_name// The name of this instance object, Thread_Object_count// The number of statically-created instance objects, Thread_Object_first// The handle of the first dynamically-created instance object, or NULL, Thread_Object_get// The handle of the i-th statically-created instance object (array == NULL), Thread_Object_heap// The heap used to allocate dynamically-created instance objects, Thread_Object_next// The handle of the next dynamically-created instance object, or NULL, Thread_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
Thread_Module_getMask// Returns the diagnostics mask for this module, Thread_Module_hasMask// Test whether this module has a diagnostics mask, Thread_Module_heap// The heap from which this module allocates memory, Thread_Module_id// Get this module's unique id, Thread_Module_setMask// Set the diagnostics mask for this module, Thread_Module_startupDone// Test if this module has completed startup
Defines
#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
Typedefs
typedef enum
Thread_CompStatus// Status returned by compareOsPriorities when an error occurs ...
typedef Thread_Object *
Thread_Handle// Client reference to an instance object;
typedef struct
Thread_Object// Opaque internal representation of an instance object Thread_Object;
typedef struct
Thread_Params// Instance config-params structure ...
typedef enum
Thread_Priority// Thread priorities which are mapped to OS specific value by Proxy ...
typedef Void 
(*Thread_RunFxn// Typedef for thread function)(IArg);
typedef struct
Thread_Stat// Struct to hold thread statistics from stat ...
typedef struct
Thread_Struct// Opaque client structure large enough to hold an instance object Thread_Struct;
Constants
extern const Assert_Id 
Thread_A_zeroTimeout// Assert when timeout passed to sleep is zero;
extern const SizeT 
Thread_defaultStackSize// Default thread stack size;
 
DETAILS
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.
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');
 
const Thread_GETPRI_FAILED
index URL

Status returned by getPri when an error occurs

C synopsis target-domain
#define Thread_GETPRI_FAILED (Int)-2
 
 
const Thread_INVALID_OS_PRIORITY
index URL

Invalid OS priority value

C synopsis target-domain
#define Thread_INVALID_OS_PRIORITY (Int)0
 
 
enum Thread_CompStatus
index URL

Status returned by compareOsPriorities when an error occurs

C synopsis target-domain
typedef enum Thread_CompStatus {
    Thread_CompStatus_ERROR,
    Thread_CompStatus_LOWER,
    Thread_CompStatus_EQUAL,
    Thread_CompStatus_HIGHER
} Thread_CompStatus;
 
 
enum Thread_Priority
index URL

Thread priorities which are mapped to OS specific value by Proxy

C synopsis target-domain
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
index URL

Typedef for thread function

C synopsis target-domain
typedef Void (*Thread_RunFxn)(IArg);
 
 
struct Thread_Stat
index URL

Struct to hold thread statistics from stat

C synopsis target-domain
typedef struct Thread_Stat {
    SizeT stackSize;
    SizeT stackUsed;
} Thread_Stat;
 
 
config Thread_A_zeroTimeout  // module-wide
index URL

Assert when timeout passed to sleep is zero

C synopsis target-domain
extern const Assert_Id Thread_A_zeroTimeout;
 
 
config Thread_defaultStackSize  // module-wide
index URL

Default thread stack size

C synopsis target-domain
extern const SizeT Thread_defaultStackSize;
 
 
Thread_compareOsPriorities()  // module-wide
index URL

Compare two os specific priority values and find out which one represents a higher priority

C synopsis target-domain
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
index URL

Return the currently executing thread's handle

C synopsis target-domain
Thread_Handle Thread_self(Error_Block *eb);
 
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
index URL

Sleep for given number of microseconds

C synopsis target-domain
Bool Thread_sleep(UInt timeout, Error_Block *eb);
 
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
index URL

Start threads running

C synopsis target-domain
Bool Thread_start(Error_Block *eb);
 
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
index URL

Yield the currently scheduled thread

C synopsis target-domain
Bool Thread_yield(Error_Block *eb);
 
ARGUMENTS
eb — Pointer to Error.Block
RETURNS
true for success; false for error
Module-Wide Built-Ins
index URL

C synopsis target-domain
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(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Thread_Object Thread_Object;
// Opaque internal representation of an instance object
 
typedef Thread_Object *Thread_Handle;
// Client reference to an instance object
 
typedef struct Thread_Struct Thread_Struct;
// Opaque client structure large enough to hold an instance object
 
Thread_Handle Thread_handle(Thread_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
Thread_Struct *Thread_struct(Thread_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Thread_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    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(Thread_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config Thread_arg  // instance
index URL

Thread function argument. Default is 0

C synopsis target-domain
struct Thread_Params {
      ...
    IArg arg;
 
 
config Thread_osPriority  // instance
index URL

OS specific thread priority

C synopsis target-domain
struct Thread_Params {
      ...
    Int osPriority;
 
DETAILS
Used to specify an OS specific value for priority. If set this value takes precedence over priority.
 
config Thread_priority  // instance
index URL

Specify the new thread's priority

C synopsis target-domain
struct Thread_Params {
      ...
    Thread_Priority priority;
 
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  // instance
index URL

Thread stack size

C synopsis target-domain
struct Thread_Params {
      ...
    SizeT stackSize;
 
DETAILS
The default value of 0 means that defaultStackSize is used.
 
config Thread_tls  // instance
index URL

Thread local storage

C synopsis target-domain
struct Thread_Params {
      ...
    Ptr tls;
 
DETAILS
User data associated with a thread. Must persist for the life of the thread.
Instance Creation
index URL

C synopsis target-domain
Thread_Handle Thread_create(Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void Thread_construct(Thread_Struct *structP, Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb);
// 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.
Instance Deletion
index URL

C synopsis target-domain
Void Thread_delete(Thread_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void Thread_destruct(Thread_Struct *structP);
// Finalize the instance object inside the provided structure
 
Thread_getOsHandle()  // instance
index URL

Get the OS thread handle

C synopsis target-domain
Ptr Thread_getOsHandle(Thread_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Thread instance object
RETURNS
OS thread handle
 
Thread_getOsPriority()  // instance
index URL

Obtain a thread's OS specific priority

C synopsis target-domain
Int Thread_getOsPriority(Thread_Handle handle, Error_Block *eb);
 
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()  // instance
index URL

Obtain a thread's priority

C synopsis target-domain
Thread_Priority Thread_getPriority(Thread_Handle handle, Error_Block *eb);
 
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()  // instance
index URL

Obtain a thread's local storage

C synopsis target-domain
Ptr Thread_getTls(Thread_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Thread instance object
RETURNS
null when tls has not been set.
 
Thread_join()  // instance
index URL

Block calling thread until given thread terminates

C synopsis target-domain
Bool Thread_join(Thread_Handle handle, Error_Block *eb);
 
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()  // instance
index URL

Set a thread's priority

C synopsis target-domain
Bool Thread_setOsPriority(Thread_Handle handle, Int newPri, Error_Block *eb);
 
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()  // instance
index URL

Set a thread's priority

C synopsis target-domain
Bool Thread_setPriority(Thread_Handle handle, Thread_Priority newPri, Error_Block *eb);
 
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()  // instance
index URL

Change a thread's local storage

C synopsis target-domain
Void Thread_setTls(Thread_Handle handle, Ptr tls);
 
ARGUMENTS
handle — handle of a previously-created Thread instance object
tls — tls
 
Thread_stat()  // instance
index URL

Get thread statistics

C synopsis target-domain
Bool Thread_stat(Thread_Handle handle, Thread_Stat *buf, Error_Block *eb);
 
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
Instance Built-Ins
index URL

C synopsis target-domain
Int Thread_Object_count();
// The number of statically-created instance objects
 
Thread_Handle Thread_Object_get(Thread_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
Thread_Handle Thread_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
Thread_Handle Thread_Object_next(Thread_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle Thread_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *Thread_Handle_label(Thread_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String Thread_Handle_name(Thread_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in xdc/runtime/knl/Thread.xdc
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);
 
 
proxy Thread.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
Thread.Proxy = IThreadSupport.Module null
// some delegate module inheriting the IThreadSupport interface
    Thread.Proxy.delegate$ = IThreadSupport.Module null
    // explicit access to the currently bound delegate module
    Thread.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
 
 
const Thread.GETPRI_FAILED
index URL

Status returned by getPri when an error occurs

XDCscript usage meta-domain
const Thread.GETPRI_FAILED = -2;
 
C SYNOPSIS
Thread_GETPRI_FAILED
 
const Thread.INVALID_OS_PRIORITY
index URL

Invalid OS priority value

XDCscript usage meta-domain
const Thread.INVALID_OS_PRIORITY = 0;
 
C SYNOPSIS
Thread_INVALID_OS_PRIORITY
 
enum Thread.CompStatus
index URL

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;
 
C SYNOPSIS
Thread_CompStatus
 
enum Thread.Priority
index URL

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;
 
C SYNOPSIS
Thread_Priority
 
struct Thread.Stat
index URL

Struct to hold thread statistics from stat

XDCscript usage meta-domain
var obj = new Thread.Stat;
 
    obj.stackSize = SizeT  ...
    obj.stackUsed = SizeT  ...
 
C SYNOPSIS
Thread_Stat
 
config Thread.A_zeroTimeout  // module-wide
index URL

Assert when timeout passed to sleep is zero

XDCscript usage meta-domain
Thread.A_zeroTimeout = Assert.Desc {
    msg: "A_zeroTimeout: Timeout value annot be zero"
};
 
C SYNOPSIS
Thread_A_zeroTimeout
 
config Thread.defaultStackSize  // module-wide
index URL

Default thread stack size

XDCscript usage meta-domain
Thread.defaultStackSize = SizeT 0;
 
C SYNOPSIS
Thread_defaultStackSize
 
metaonly config Thread.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Thread.common$ = Types.Common$ undefined;
 
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.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Thread.Params;
// Instance config-params object
    params.arg = IArg 0;
    // Thread function argument. Default is 0
    params.osPriority = Int Thread.INVALID_OS_PRIORITY;
    // OS specific thread priority
    params.priority = Thread.Priority Thread.Priority_NORMAL;
    // Specify the new thread's priority
    params.stackSize = SizeT 0;
    // Thread stack size
    params.tls = Ptr null;
    // Thread local storage
 
config Thread.arg  // instance
index URL

Thread function argument. Default is 0

XDCscript usage meta-domain
var params = new Thread.Params;
  ...
params.arg = IArg 0;
 
C SYNOPSIS
null
 
config Thread.osPriority  // instance
index URL

OS specific thread priority

XDCscript usage meta-domain
var params = new Thread.Params;
  ...
params.osPriority = Int Thread.INVALID_OS_PRIORITY;
 
DETAILS
Used to specify an OS specific value for priority. If set this value takes precedence over priority.
C SYNOPSIS
null
 
config Thread.priority  // instance
index URL

Specify the new thread's priority

XDCscript usage meta-domain
var params = new Thread.Params;
  ...
params.priority = Thread.Priority Thread.Priority_NORMAL;
 
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.
C SYNOPSIS
null
 
config Thread.stackSize  // instance
index URL

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.
C SYNOPSIS
null
 
config Thread.tls  // instance
index URL

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.
C SYNOPSIS
null
Instance Creation
index URL

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
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.
generated on Thu, 27 Sep 2012 23:21:10 GMT