module ti.sdo.xdcruntime.linux.ThreadSupport
C synopsis target-domain sourced in ti/sdo/xdcruntime/linux/ThreadSupport.xdc
#include <ti/sdo/xdcruntime/linux/ThreadSupport.h>
Functions
Void
Void
Void
Void
Functions common to all IThreadSupport modules
Int 
Ptr 
Int 
Ptr 
Bool 
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 struct
typedef struct
typedef enum
typedef Void 
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const Error_Id 
extern const Error_Id 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
 
const ThreadSupport_GETPRI_FAILED

The error status for getPriority when an error is captured in the Error.Block

C synopsis target-domain
#define ThreadSupport_GETPRI_FAILED (Int)-2
const ThreadSupport_INVALID_OS_PRIORITY

Invalid OS priority value

C synopsis target-domain
#define ThreadSupport_INVALID_OS_PRIORITY (Int)0
enum ThreadSupport_CompStatus

Status returned by compareOsPriorities when an error occurs

C synopsis target-domain
typedef enum ThreadSupport_CompStatus {
    ThreadSupport_CompStatus_ERROR,
    ThreadSupport_CompStatus_LOWER,
    ThreadSupport_CompStatus_EQUAL,
    ThreadSupport_CompStatus_HIGHER
} ThreadSupport_CompStatus;
enum ThreadSupport_Priority

Thread priorities which are mapped to OS specific value by Proxy

C synopsis target-domain
typedef enum ThreadSupport_Priority {
    ThreadSupport_Priority_INVALID,
    ThreadSupport_Priority_LOWEST,
    ThreadSupport_Priority_BELOW_NORMAL,
    ThreadSupport_Priority_NORMAL,
    ThreadSupport_Priority_ABOVE_NORMAL,
    ThreadSupport_Priority_HIGHEST
} ThreadSupport_Priority;
typedef ThreadSupport_RunFxn

typedef for function that gets called when the Thread runs

C synopsis target-domain
typedef Void (*ThreadSupport_RunFxn)(IArg);
struct ThreadSupport_Stat

Struct to hold thread statistics from stat

C synopsis target-domain
typedef struct ThreadSupport_Stat {
    SizeT stackSize;
    SizeT stackUsed;
} ThreadSupport_Stat;
config ThreadSupport_A_POSIX_Error  // module-wide
C synopsis target-domain
extern const Assert_Id ThreadSupport_A_POSIX_Error;
config ThreadSupport_E_POSIX_Error  // module-wide
C synopsis target-domain
extern const Error_Id ThreadSupport_E_POSIX_Error;
config ThreadSupport_E_priority  // module-wide
C synopsis target-domain
extern const Error_Id ThreadSupport_E_priority;
config ThreadSupport_L_finish  // module-wide
C synopsis target-domain
extern const Log_Event ThreadSupport_L_finish;
config ThreadSupport_L_join  // module-wide
C synopsis target-domain
extern const Log_Event ThreadSupport_L_join;
config ThreadSupport_L_start  // module-wide
C synopsis target-domain
extern const Log_Event ThreadSupport_L_start;
ThreadSupport_compareOsPriorities()  // module-wide

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

C synopsis target-domain
Int ThreadSupport_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
ThreadSupport_self()  // module-wide

Acquire the currently executing thread's handle

C synopsis target-domain
IThreadSupport_Handle ThreadSupport_self(Error_Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.self for more details.
RETURNS
Handle in case of success; null for error;
ThreadSupport_sleep()  // module-wide

Sleep for certain number of microseconds

C synopsis target-domain
Bool ThreadSupport_sleep(UInt timeout, Error_Block *eb);
ARGUMENTS
timeout — timeout in microseconds
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.sleep for more details.
RETURNS
true for success; false for failure
ThreadSupport_start()  // module-wide

Start threads running

C synopsis target-domain
Bool ThreadSupport_start(Error_Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.start for more details.
RETURNS
true for success; false for failure
ThreadSupport_yield()  // module-wide

Yield the currently scheduled thread

C synopsis target-domain
Bool ThreadSupport_yield(Error_Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.yield for more details.
RETURNS
true for success; false for failure
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId ThreadSupport_Module_id();
// Get this module's unique id
 
Bool ThreadSupport_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle ThreadSupport_Module_heap();
// The heap from which this module allocates memory
 
Bool ThreadSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 ThreadSupport_Module_getMask();
// Returns the diagnostics mask for this module
 
Void ThreadSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct ThreadSupport_Object ThreadSupport_Object;
// Opaque internal representation of an instance object
 
typedef ThreadSupport_Object *ThreadSupport_Handle;
// Client reference to an instance object
 
typedef struct ThreadSupport_Struct ThreadSupport_Struct;
// Opaque client structure large enough to hold an instance object
 
ThreadSupport_Handle ThreadSupport_handle(ThreadSupport_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
ThreadSupport_Struct *ThreadSupport_struct(ThreadSupport_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct ThreadSupport_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    IArg arg;
    // Thread function argument. Default is NULL
    Int osPriority;
    // OS specific thread priority
    IThreadSupport_Priority priority;
    // Thread priority
    SizeT stackSize;
    // Thread stack size. If left at zero, OS default is used
    Ptr tls;
    // User-specified thread local storage data
} ThreadSupport_Params;
 
Void ThreadSupport_Params_init(ThreadSupport_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config ThreadSupport_arg  // instance

Thread function argument. Default is NULL

C synopsis target-domain
      ...
    IArg arg;
config ThreadSupport_osPriority  // instance

OS specific thread priority

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

Thread priority

C synopsis target-domain
      ...
    IThreadSupport_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 ThreadSupport_stackSize  // instance

Thread stack size. If left at zero, OS default is used

C synopsis target-domain
      ...
    SizeT stackSize;
config ThreadSupport_tls  // instance

User-specified thread local storage data

C synopsis target-domain
      ...
    Ptr tls;
Instance Creation

C synopsis target-domain
ThreadSupport_Handle ThreadSupport_create(IThreadSupport_RunFxn fxn, const ThreadSupport_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void ThreadSupport_construct(ThreadSupport_Struct *structP, IThreadSupport_RunFxn fxn, const ThreadSupport_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 ThreadSupport_delete(ThreadSupport_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void ThreadSupport_destruct(ThreadSupport_Struct *structP);
// Finalize the instance object inside the provided structure
ThreadSupport_getOsHandle()  // instance

Get the OS thread handle

C synopsis target-domain
Ptr ThreadSupport_getOsHandle(ThreadSupport_Handle handle);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
RETURNS
null in case of error
ThreadSupport_getOsPriority()  // instance

Obtain a thread's os specific priority

C synopsis target-domain
Int ThreadSupport_getOsPriority(ThreadSupport_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created ThreadSupport 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.
Refer to xdc.runtime.knl.Thread.getOsPriority for more details.
RETURNS
thread priority in case of success; GETPRI_FAILED in case of error;
ThreadSupport_getPriority()  // instance

Obtain a thread's priority

C synopsis target-domain
IThreadSupport_Priority ThreadSupport_getPriority(ThreadSupport_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.getPriority for more details.
RETURNS
thread priority in case of success; Priority_INVALID in case of error;
ThreadSupport_getTls()  // instance

Obtain a thread's local storage pointer

C synopsis target-domain
Ptr ThreadSupport_getTls(ThreadSupport_Handle handle);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
RETURNS
null in case of error
ThreadSupport_join()  // instance

Join on a Thread

C synopsis target-domain
Bool ThreadSupport_join(ThreadSupport_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.join for more details.
RETURNS
true for success; false for failure
ThreadSupport_setOsPriority()  // instance

Set a thread's priority

C synopsis target-domain
Bool ThreadSupport_setOsPriority(ThreadSupport_Handle handle, Int newPri, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created ThreadSupport 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
Refer to xdc.runtime.knl.Thread.setOsPriority for more details.
RETURNS
true for success; false for failure
ThreadSupport_setPriority()  // instance

Set a thread's priority

C synopsis target-domain
Bool ThreadSupport_setPriority(ThreadSupport_Handle handle, IThreadSupport_Priority newPri, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
newPri — new thread priority
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.setPriority for more details.
RETURNS
true for success; false for failure
ThreadSupport_setTls()  // instance

Set a thread's local storage pointer

C synopsis target-domain
Void ThreadSupport_setTls(ThreadSupport_Handle handle, Ptr tls);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
tls — thread tls
ThreadSupport_stat()  // instance

Obtain a thread's stats

C synopsis target-domain
Bool ThreadSupport_stat(ThreadSupport_Handle handle, IThreadSupport_Stat *buf, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created ThreadSupport instance object
buf — Pointer to Stat
eb — Pointer to Error.Block
RETURNS
true for success; false for failure
Instance Convertors

C synopsis target-domain
IThreadSupport_Handle ThreadSupport_Handle_upCast(ThreadSupport_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
ThreadSupport_Handle ThreadSupport_Handle_downCast(IThreadSupport_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int ThreadSupport_Object_count();
// The number of statically-created instance objects
 
ThreadSupport_Handle ThreadSupport_Object_get(ThreadSupport_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
ThreadSupport_Handle ThreadSupport_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
ThreadSupport_Handle ThreadSupport_Object_next(ThreadSupport_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle ThreadSupport_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *ThreadSupport_Handle_label(ThreadSupport_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String ThreadSupport_Handle_name(ThreadSupport_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/xdcruntime/linux/ThreadSupport.xdc
var ThreadSupport = xdc.useModule('ti.sdo.xdcruntime.linux.ThreadSupport');
module-wide constants & types
        const ThreadSupport.CompStatus_ERROR;
        const ThreadSupport.CompStatus_LOWER;
        const ThreadSupport.CompStatus_EQUAL;
        const ThreadSupport.CompStatus_HIGHER;
        const ThreadSupport.Priority_INVALID;
        const ThreadSupport.Priority_LOWEST;
        const ThreadSupport.Priority_BELOW_NORMAL;
        const ThreadSupport.Priority_NORMAL;
        const ThreadSupport.Priority_ABOVE_NORMAL;
        const ThreadSupport.Priority_HIGHEST;
        obj.stackSize = SizeT  ...
        obj.stackUsed = SizeT  ...
module-wide config parameters
        msg: "A_POSIX_Error: a POSIX function returned failure"
    };
        msg: "E_POSIX_Error: a POSIX function returned failure, errno is %d"
    };
        msg: "E_priority: Thread priority is invalid %d"
    };
        mask: Diags.LIFECYCLE,
        msg: "--> finish: (%p)"
    };
        mask: Diags.LIFECYCLE,
        msg: "--> join: (%p)"
    };
        mask: Diags.LIFECYCLE,
        msg: "<-- start: (%p)"
    };
per-instance config parameters
    var params = new ThreadSupport.Params// Instance config-params object;
        params.arg// Thread function argument. Default is NULL = IArg null;
        params.tls// User-specified thread local storage data = Ptr null;
per-instance creation
    var inst = ThreadSupport.create// Create an instance-object(Void(*)(IArg) fxn, params);
 
const ThreadSupport.GETPRI_FAILED

The error status for getPriority when an error is captured in the Error.Block

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

Invalid OS priority value

XDCscript usage meta-domain
const ThreadSupport.INVALID_OS_PRIORITY = 0;
C SYNOPSIS
enum ThreadSupport.CompStatus

Status returned by compareOsPriorities when an error occurs

XDCscript usage meta-domain
values of type ThreadSupport.CompStatus
    const ThreadSupport.CompStatus_ERROR;
    const ThreadSupport.CompStatus_LOWER;
    const ThreadSupport.CompStatus_EQUAL;
    const ThreadSupport.CompStatus_HIGHER;
C SYNOPSIS
enum ThreadSupport.Priority

Thread priorities which are mapped to OS specific value by Proxy

XDCscript usage meta-domain
values of type ThreadSupport.Priority
    const ThreadSupport.Priority_INVALID;
    const ThreadSupport.Priority_LOWEST;
    const ThreadSupport.Priority_BELOW_NORMAL;
    const ThreadSupport.Priority_NORMAL;
    const ThreadSupport.Priority_ABOVE_NORMAL;
    const ThreadSupport.Priority_HIGHEST;
C SYNOPSIS
struct ThreadSupport.Stat

Struct to hold thread statistics from stat

XDCscript usage meta-domain
var obj = new ThreadSupport.Stat;
 
    obj.stackSize = SizeT  ...
    obj.stackUsed = SizeT  ...
C SYNOPSIS
config ThreadSupport.A_POSIX_Error  // module-wide
XDCscript usage meta-domain
ThreadSupport.A_POSIX_Error = Assert.Desc {
    msg: "A_POSIX_Error: a POSIX function returned failure"
};
C SYNOPSIS
config ThreadSupport.E_POSIX_Error  // module-wide
XDCscript usage meta-domain
ThreadSupport.E_POSIX_Error = Error.Desc {
    msg: "E_POSIX_Error: a POSIX function returned failure, errno is %d"
};
C SYNOPSIS
config ThreadSupport.E_priority  // module-wide
XDCscript usage meta-domain
ThreadSupport.E_priority = Error.Desc {
    msg: "E_priority: Thread priority is invalid %d"
};
C SYNOPSIS
config ThreadSupport.L_finish  // module-wide
XDCscript usage meta-domain
ThreadSupport.L_finish = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> finish: (%p)"
};
C SYNOPSIS
config ThreadSupport.L_join  // module-wide
XDCscript usage meta-domain
ThreadSupport.L_join = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> join: (%p)"
};
C SYNOPSIS
config ThreadSupport.L_start  // module-wide
XDCscript usage meta-domain
ThreadSupport.L_start = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- start: (%p)"
};
C SYNOPSIS
metaonly config ThreadSupport.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
ThreadSupport.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 ThreadSupport.Params;
// Instance config-params object
    params.arg = IArg null;
    // Thread function argument. Default is NULL
    params.osPriority = Int IThreadSupport.INVALID_OS_PRIORITY;
    // OS specific thread priority
    // Thread priority
    params.stackSize = SizeT 0;
    // Thread stack size. If left at zero, OS default is used
    params.tls = Ptr null;
    // User-specified thread local storage data
config ThreadSupport.arg  // instance

Thread function argument. Default is NULL

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

OS specific thread priority

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

Thread priority

XDCscript usage meta-domain
var params = new ThreadSupport.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 ThreadSupport.stackSize  // instance

Thread stack size. If left at zero, OS default is used

XDCscript usage meta-domain
var params = new ThreadSupport.Params;
  ...
params.stackSize = SizeT 0;
C SYNOPSIS
config ThreadSupport.tls  // instance

User-specified thread local storage data

XDCscript usage meta-domain
var params = new ThreadSupport.Params;
  ...
params.tls = Ptr null;
C SYNOPSIS
Instance Creation

XDCscript usage meta-domain
var params = new ThreadSupport.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = ThreadSupport.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 Fri, 29 Oct 2010 00:26:49 GMT