module xdc.runtime.knl.Thread

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 
Void
Void
Void
Ptr 
Int 
Ptr 
Bool 
Void
Bool 
Bool 
Void 
Bool 
Bool 
Bool 
Bool 
Functions common to all target instances
Functions common to all target modules
Defines
#define
#define
Typedefs
typedef enum
typedef Thread_Object *
typedef struct
typedef struct
typedef enum
typedef Void 
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const SizeT 
 
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

Status returned by getPri when an error occurs

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

Invalid OS priority value

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

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

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

Typedef for thread function

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

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

Assert when timeout passed to sleep is zero

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

Default thread stack size

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

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

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

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

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

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

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

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

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

Thread function argument. Default is 0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.delegate$ = IThreadSupport.Module null
        Thread.Proxy.abstractInstances$ = false
module-wide constants & types
 
        const Thread.CompStatus_ERROR;
        const Thread.CompStatus_LOWER;
        const Thread.CompStatus_EQUAL;
        const Thread.CompStatus_HIGHER;
 
        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;
 
        obj.stackSize = SizeT  ...
        obj.stackUsed = SizeT  ...
module-wide config parameters
        msg: "A_zeroTimeout: Timeout value annot be zero"
    };
 
per-instance config parameters
    var params = new Thread.Params// Instance config-params object;
        params.arg// Thread function argument. Default is 0 = IArg 0;
        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

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

Status returned by getPri when an error occurs

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

Invalid OS priority value

XDCscript usage meta-domain
const Thread.INVALID_OS_PRIORITY = 0;
 
C SYNOPSIS
 
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;
 
C SYNOPSIS
 
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;
 
C SYNOPSIS
 
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  ...
 
C SYNOPSIS
 
config Thread.A_zeroTimeout  // module-wide

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
 
config Thread.defaultStackSize  // module-wide

Default thread stack size

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

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

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

Thread function argument. Default is 0

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

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
 
config Thread.priority  // 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.
C SYNOPSIS
 
config Thread.stackSize  // 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.
C SYNOPSIS
 
config Thread.tls  // 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.
C SYNOPSIS
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
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, 01 Mar 2012 16:58:46 GMT