This chapter provides reference documentation for the threading APIs provided by Palm OS. These APIs allow you to work with threads and thread groups, semaphores, condition variables, and critical sections. As well, the threading APIs include a set of atomic operations that some applications may find useful.
The contents of this chapter is divided into the following sections:
SysThread Structures and Types
SysThread Constants
SysThread Functions and Macros
Application-Defined Functions
The header file SysThread.h
declares the API that this chapter describes.
This chapter provides reference information on the individual types, constants, and functions that you use when writing multi-threaded applications. For background information as well as tips on using these APIs, see Chapter 8, "Threading."
SysThread Structures and Types
SysConditionVariableType Typedef
Purpose
Defines a condition variable upon which threads will block until the variable becomes open.
Declared In
SysThread.h
Prototype
typedef void *SysConditionVariableType
Comments
Variables of this type should be initialized to sysConditionVariableInitializer. This marks the condition variable as closed: to open it, call SysConditionVariableOpen()
. To block on the condition variable, use SysConditionVariableWait()
.
SysCriticalSectionType Typedef
Purpose
Defines a mutex that is used to control access to a critical section.
Declared In
SysThread.h
Prototype
typedef void *SysCriticalSectionType
Comments
Use SysCriticalSectionType
variables in conjunction with SysCriticalSectionEnter()
and SysCriticalSectionExit()
to prevent more than one thread from executing the code in the critical section at the same time.
Initialize variables of this type to sysCriticalSectionInitializer.
SysThreadExitCallbackID Typedef
Purpose
ID of a thread exit callback function.
Declared In
SysThread.h
Prototype
typedef uint32_t SysThreadExitCallbackID
Comments
This identifier can be returned to you when you install the exit callback function with SysThreadInstallExitCallback()
. You use it to identify the callback function to be removed when calling SysThreadRemoveExitCallback()
.
SysThreadGroupHandle Typedef
Purpose
Declared In
SysThread.h
Prototype
typedef SysThreadGroupType *SysThreadGroupHandle
Comments
Thread groups are identified by a SysThreadGroupHandle
. You obtain a thread group handle when you create the group with SysThreadGroupCreate()
. You then supply this handle when adding threads to the group (at creation time, with SysThreadCreate()
), or when waiting on the group's threads or destroying the group (SysThreadGroupWait()
and SysThreadGroupDestroy()
, respectively).
SysThreadGroupTag Struct
Purpose
Identifier for an internal structure that represents a thread group.
Declared In
SysThread.h
Prototype
struct SysThreadGroupTag
SysThreadGroupType Struct
Purpose
Type definition for an internal structure that represents a thread group.
Declared In
SysThread.h
Prototype
typedef struct SysThreadGroupTag SysThreadGroupType
SysTSDSlotID Typedef
Purpose
Thread-specific data (TSD) slot identifier.
Declared In
SysThread.h
Prototype
typedef uint32_t SysTSDSlotID
Comments
You receive a SysTSDSlotID
when you allocate a new thread-specific data slot with SysTSDAllocate()
.
SysThread Constants
Thread Priorities
Purpose
Common thread priority values.
Declared In
SysThread.h
Constants
-
#define sysThreadPriorityBestApp 80
- The highest priority for the application process and any thread created by it.
-
#define sysThreadPriorityBestSystem 5
- The highest priority reserved for system programs.
-
#define sysThreadPriorityBestUser 30
- The highest priority that should be used by user programs.
-
#define sysThreadPriorityDisplay 60
- Priority that can be used when drawing to the screen.
-
#define sysThreadPriorityHigh sysThreadPriorityRealTime
- An alias for
sysThreadPriorityRealTime
. -
#define sysThreadPriorityLow sysThreadPriorityLowered
- An alias for
sysThreadPriorityLowered
. -
#define sysThreadPriorityLowered 100
- Priority to be used by background threads or threads that are "CPU hogs."
-
#define sysThreadPriorityNormal 80
- Default priority for event handling.
-
#define sysThreadPriorityRaised 70
- Increased priority (over
sysThreadPriorityNormal
) for user operations. -
#define sysThreadPriorityRealTime 40
- Priority to be used by time-critical code, such as that doing audio recording and playback.
-
#define sysThreadPriorityTransaction 65
- Priority to be used for UI transactions.
-
#define sysThreadPriorityUrgentDisplay 50
- Priority that can be used during event collection and dispatching.
Comments
SysThreadCreate()
and EvtCreateBackgroundThread()
do not guarantee that the requested priority will be satisfied. A return value of errNone
does not guarantee that the thread has been created at requested priority. Depending upon the context in which the function was called, the actual thread priority may be lower than what was requested. In operating system processes, the highest priority is sysThreadPriorityBestSystem. For an application, the highest is sysThreadPriorityBestApp. Accordingly, if an application calls SysThreadCreate()
and specifies a priority of 79, the thread will be created successfully but the actual priority of the new thread will be 80.
Miscellaneous System Thread Constants
Purpose
The header file SysThread.h
also declares these constants.
Declared In
SysThread.h
Constants
-
#define sysConditionVariableInitializer NULL
- Initial value for a condition variable of type
SysConditionVariableType
. -
#define sysCriticalSectionInitializer NULL
- Initial value for a critical section mutex of type
SysCriticalSectionType
. -
#define sysThreadNoGroup NULL
- A thread group handle value that represents "no thread group." This value is returned from
SysThreadGroupCreate()
if the thread group couldn't be created. Pass this value toSysThreadCreate()
if you don't want the thread you are creating to be part of a thread group. Note thatSysThreadCreateEZ()
only creates threads that are not part of a thread group: it callsSysThreadCreate()
and passes a value ofsysThreadNoGroup
for thegroup
parameter. -
#define sysThreadStackBasic 4*1024
- The size of a stack, in bytes, required by a typical non-UI thread.
-
#define sysThreadStackUI 8*1024
- The size of a stack, in bytes, required by a typical UI thread. Threads created with
SysThreadCreateEZ()
have a stack of this size.
Predefined TSD Slot Names Enum
Purpose
Defines a set of TSD slot names that have special meaning to the operating system.
Declared In
SysThread.h
Constants
-
sysTSDAnonymous = 0
- Anonymous slot. Supply this value for the slot name when allocating a new TSD slot (using
SysTSDAllocate()
) if you don't need to update the slot's destructor function pointer and thus don't need to give the slot a particular name.
Predefined Semaphore Counts Enum
Purpose
Defines useful semaphore count values.
Declared In
SysThread.h
Constants
-
sysSemaphoreMaxCount = 0xffff
- The greatest value that can be supplied either for the initial or maximum semaphore counts when creating a semaphore with either
SysSemaphoreCreate()
orSysSemaphoreCreateEZ()
.
timeoutFlags_t Typedef
Purpose
Variables of this type contain flags that indicate how a given timeout value should be interpreted.
Declared In
SysThread.h
Prototype
typedef uint16_t timeoutFlags_t
Constants
-
P_WAIT_FOREVER = 0x0000
- The specified timeout value should be ignored; the thread or semaphore should wait for an indefinite period of time. This flag should never be used with
SysThreadDelay()
. -
P_POLL = 0x0300
- The timeout value should be ignored, and the function should return immediately.
-
P_RELATIVE_TIMEOUT = 0x0100
- The timeout value is a number of nanoseconds that should be added to the amount of time the thread or semaphore is already scheduled to wait.
-
P_ABSOLUTE_TIMEOUT = 0x0200
- The timeout value specifies the absolute number of nanoseconds that the thread or semaphore should wait.
Comments
These flags are used in conjunction with the SysSemaphoreWait()
, SysSemaphoreWaitCount()
, and SysThreadDelay()
functions. These values are contained in a variable of type timeoutFlags_t
.
SysThread Functions and Macros
SysAtomicAdd32 Function
Purpose
Atomically adds a 32-bit quantity to a location in memory and returns the value of that memory location as it was prior to the addition.
Declared In
SysThread.h
Prototype
int32_t SysAtomicAdd32 ( int32_t volatile*ioOperandP
, int32_tiAddend
)
Parameters
-
↔ ioOperandP
- Pointer to a 32-bit quantity to which
iAddend
is to be added. -
→ iAddend
- Value to be added to
*
ioOperandP
.
Returns
Returns the value in *
ioOperandP
before iAddend
was added to it.
See Also
SysAtomicAnd32()
, SysAtomicCompareAndSwap32()
, SysAtomicOr32()
SysAtomicAnd32 Function
Purpose
Atomically ANDs a 32-bit quantity into a location in memory and returns the value of that memory location as it was prior to the AND operation.
Declared In
SysThread.h
Prototype
uint32_t SysAtomicAnd32 ( uint32_t volatile*ioOperandP
, uint32_tiValue
)
Parameters
-
↔ ioOperandP
- Pointer to a 32-bit quantity to which
ivalue
is to be ANDed. Upon return the indicated memory location contains the results of the AND operation. -
→ iValue
- Value to be ANDed with
*
ioOperandP
.
Returns
Returns the value in *
ioOperandP
before iValue
was ANDed with it.
See Also
SysAtomicAdd32()
, SysAtomicCompareAndSwap32()
, SysAtomicOr32()
SysAtomicCompareAndSwap32 Function
Purpose
In a single atomic operation, compares the contents of a location in memory with a supplied 32-bit value, and, if they are the same, changes the location in memory to a second supplied 32-bit value.
Declared In
SysThread.h
Prototype
uint32_t SysAtomicCompareAndSwap32 ( uint32_t volatile*ioOperandP
, uint32_tiOldValue
, uint32_tiNewValue
)
Parameters
-
↔ ioOperandP
- Pointer to a 32-bit quantity against which
iOldValue
is to be compared. Upon return the indicated memory location is set toiNewValue
if*
ioOperandP
proved equal toiOldValue
. -
→ iOldValue
- Value against which
*
ioOperandP
is to be compared. -
→ iNewValue
- Value to be stored in
*
ioOperandP
if*
ioOperandP
is equal toiOldValue
.
Returns
Returns 0 if the swap was performed, or 1 if the swap was not performed (thus indicating that the location pointed to by ioOperandP
wasn't equal to iOldvalue
).
See Also
SysAtomicAdd32()
, SysAtomicAnd32()
, SysAtomicOr32()
SysAtomicOr32 Function
Purpose
Atomically ORs a 32-bit quantity into a location in memory and returns the value of that memory location as it was prior to the OR operation.
Declared In
SysThread.h
Prototype
uint32_t SysAtomicOr32 ( uint32_t volatile*ioOperandP
, uint32_tiValue
)
Parameters
-
↔ ioOperandP
- Pointer to a 32-bit quantity to which
ivalue
is to be ORed. Upon return the indicated memory location contains the results of the OR operation. -
→ iValue
- Value to be ORed with
*
ioOperandP
.
Returns
Returns the value in *
ioOperandP
before iValue
was ORed with it.
See Also
SysAtomicAdd32()
, SysAtomicAnd32()
, SysAtomicCompareAndSwap32()
SysConditionVariableBroadcast Function
Purpose
Cause all threads waiting on a specified condition variable to continue.
Declared In
SysThread.h
Prototype
void SysConditionVariableBroadcast (
SysConditionVariableType *iCV
)
Parameters
Returns
Comments
All threads waiting on the specified condition variable are released. Upon completion of this function, the condition variable remains closed.
See Also
SysConditionVariableOpen()
, SysConditionVariableWait()
SysConditionVariableClose Function
Purpose
Transition a condition variable from opened to closed.
Declared In
SysThread.h
Prototype
void SysConditionVariableClose (
SysConditionVariableType *iCV
)
Parameters
Returns
Comments
If the condition variable is not open when this function is called, it is left as-is.
See Also
SysConditionVariableOpen()
, SysConditionVariableWait()
SysConditionVariableOpen Function
Purpose
Transition a condition variable from closed to opened.
Declared In
SysThread.h
Prototype
void SysConditionVariableOpen (
SysConditionVariableType *iCV
)
Parameters
Returns
Comments
All threads that are blocked on the specified condition variable are released. If the specified condition variable is already open when this function is called, it does nothing.
See Also
SysConditionVariableBroadcast()
, SysConditionVariableClose()
SysConditionVariableWait Function
Purpose
Wait for a specified condition variable to become open.
Declared In
SysThread.h
Prototype
void SysConditionVariableWait ( SysConditionVariableType*iCV
, SysCriticalSectionType*iOptionalCS
)
Parameters
-
→ iCV
- Pointer to the condition variable upon which to wait.
-
→ iOptionalCS
- Pointer to the mutex for a critical section if this function is called from within the critical section and the critical section is to be temporarily exited while this thread waits on the condition variable. Pass
NULL
if the call doesn't come from within a critical section, or if it does but other threads shouldn't be granted access to the critical section while this thread waits.
Returns
Comments
If the critical section is not open when this function is called, the calling thread is put in the WAIT state and placed in a queue associated with the specified condition variable. Once the condition variable is opened, all threads waiting on the variable are released. Note that you can also release all waiting threads by calling SysConditionVariableBroadcast()
, which, unlike SysConditionVariableOpen()
, leaves the condition variable in a closed state.
If the call to this function occurs within a critical section, you may want to supply the critical section mutex as the iOptionalCS
parameter. This causes the critical section to be exited in the event that the thread is put into the WAIT state. Once the thread is released the specified critical section is immediately re-entered. This has the effect of allowing other threads to enter the critical section while this thread is waiting on the condition variable. If the call to this function does not occur within a critical section, or if it does but other threads shouldn't be able to enter the critical section while this thread is waiting, pass NULL
for the iOptionalCS
parameter.
See Also
SysConditionVariableBroadcast()
, SysConditionVariableOpen()
SysCriticalSectionEnter Function
Purpose
Acquire a critical section—a block of code that can only be executed by one thread at a time.
Declared In
SysThread.h
Prototype
void SysCriticalSectionEnter (
SysCriticalSectionType *iCS
)
Parameters
-
→ iCS
- Pointer to a
SysCriticalSectionType
variable that acts as the mutex for the code block. This variable should be either globally or statically defined and should be initialized tosysCriticalSectionInitializer
.
Returns
Comments
Call this function at the beginning of the critical section to ensure that yours is the only process that is executing the code in the critical section—that code that is bounded by the SysCriticalSectionEnter()
and SysCriticalSectionExit()
calls.
See Also
SysCriticalSectionExit Function
Purpose
Declared In
SysThread.h
Prototype
void SysCriticalSectionExit (
SysCriticalSectionType *iCS
)
Parameters
-
→ iCS
- Pointer to a
SysCriticalSectionType
variable that acts as the mutex for the code block.
Returns
Comments
Call this function at the end of the critical section, thereby allowing another process to enter the critical section.
See Also
SysCurrentThread Function
Purpose
Return the identity of the current thread.
Declared In
SysThread.h
Prototype
SysHandle SysCurrentThread ( void )
Parameters
Returns
Returns the thread ID of the current thread.
SysGetRunTime Function
Purpose
Get the length of time since last reset, in nanoseconds.
Declared In
SysThread.h
Prototype
nsecs_t SysGetRunTime ( void )
Parameters
Returns
Returns the amount of time, in nanoseconds, since the last reset.
SysSemaphoreCreate Function
Purpose
Create a new counting semaphore with the specified initial count and maximum count values.
Declared In
SysThread.h
Prototype
status_t SysSemaphoreCreate ( uint32_tinitialCount
, uint32_tmaxCount
, uint32_tflags
, SysHandle*outSemaphore
)
Parameters
-
→ initialCount
- The initial count of the newly-created semaphore. This value can range from zero to
sysSemaphoreMaxCount
. Typically, this represents the number of objects available in a resource pool. -
→ maxCount
- The maximum count of the newly-created semaphore. This value can range from one to
sysSemaphoreMaxCount
. The maximum count typically represents the maximum number of objects that can be in the resource pool. -
→ flags
- Flags that specify how the semaphore is to be created. This parameter is currently ignored; applications should pass zero for
flags
. -
← outSemaphore
- ID of the newly-created semaphore.
Returns
Returns errNone
if the semaphore was successfully created, or one of the following otherwise:
-
sysErrOutOfRange
-
initialCount
ormaxCount
exceedssysSemaphoreMaxCount
. -
sysErrParamErr
-
initialCount
exceedsmaxCount
. -
sysErrNoFreeResource
- All possible semaphores are already in use.
Comments
Counting semaphores are used to keep track of the availability of a resource within a pool of limited size.
See Also
SysSemaphoreCreateEZ()
, SysSemaphoreDestroy()
SysSemaphoreCreateEZ Function
Purpose
Creates a new counting semaphore with a maximum count value of sysSemaphoreMaxCount (65535).
Declared In
SysThread.h
Prototype
status_t SysSemaphoreCreateEZ ( uint32_tinitialCount
, SysHandle*outSemaphore
)
Parameters
-
→ initialCount
- The initial count of the newly-created semaphore. This value can range from zero to
sysSemaphoreMaxCount
. -
← outSemaphore
- ID of the newly-created semaphore.
Returns
Returns errNone
if the semaphore was successfully created, or one of the following otherwise:
-
sysErrOutOfRange
-
initialCount
exceedssysSemaphoreMaxCount
. -
sysErrNoFreeResource
- All possible semaphores are already in use.
Comments
This function simply calls SysSemaphoreCreate()
and passes a value of zero for the flags
parameter and a value of sysSemaphoreMaxCount for the maxCount
parameter.
See Also
SysSemaphoreCreate()
, SysSemaphoreDestroy()
SysSemaphoreDestroy Function
Purpose
Declared In
SysThread.h
Prototype
status_t SysSemaphoreDestroy (
SysHandle semaphore
)
Parameters
Returns
Comments
Any threads that are blocked on this semaphore are released and their return values are set to kalErrObjectDestroyed
.
See Also
SysSemaphoreCreate()
, SysSemaphoreCreateEZ()
SysSemaphoreSignal Function
Purpose
Release a single resource back to the semaphore. One of the threads waiting on the semaphore (assuming that there are any) is released.
Declared In
SysThread.h
Prototype
status_t SysSemaphoreSignal (
SysHandle semaphore
)
Parameters
Returns
Returns errNone
if the maximum semaphore count wasn't exceeded, or kalErrLimitReached
if the supplied count would cause the semaphore's count to exceed the maximum value specified when the semaphore was created.
Comments
This function is equivalent to calling SysSemaphoreSignalCount()
with a count of 1. See the comments under that function for more on how this function operates.
See Also
SysSemaphoreSignalCount()
, SysSemaphoreWait()
SysSemaphoreSignalCount Function
Purpose
Release a specified number of resources back to the semaphore. As a result, as many threads as possible that are waiting on the semaphore are released.
Declared In
SysThread.h
Prototype
status_t SysSemaphoreSignalCount ( SysHandlesemaphore
, uint32_tcount
)
Parameters
-
→ semaphore
- ID of the semaphore to which resources are to be released.
-
→ count
- The amount to be added to the semaphore's count.
Returns
Returns errNone
if the maximum semaphore count wasn't exceeded, or kalErrLimitReached
if the supplied count would cause the semaphore's count to exceed the maximum value specified when the semaphore was created.
Comments
Use this function to return one or more resources to the specified semaphore. If there are threads waiting at the semaphore, as many threads as possible (given the new available resource count) are released either to the RUN or READY states. After this the semaphore's new resource count becomes its old count, plus count
, minus the resources consumed by the newly-released threads.
Note that it is not an error if the semaphore count exceeds the initial semaphore count that was specified when the semaphore was created. If a semaphore is going to be used for exclusive control, create the semaphore with the maximum count equal to the initial semaphore count.
See Also
SysSemaphoreSignal()
, SysSemaphoreWaitCount()
SysSemaphoreWait Function
Purpose
Obtains a single resource from a specified semaphore.
Declared In
SysThread.h
Prototype
status_t SysSemaphoreWait ( SysHandlesemaphore
, timeoutFlags_tiTimeoutFlags
, nsecs_tiTimeout
)
Parameters
-
→ semaphore
- ID of the semaphore from which resources are to be acquired.
-
→ iTimeoutFlags
- A value specifying how the timeout value should be interpreted. See
timeoutFlags_t
. -
→ iTimeout
- Timeout value, in nanoseconds.
Returns
Returns errNone
if the specified number of resources were successfully obtained, or one of the following otherwise:
-
sysErrTimeout
- There aren't
count
resources available, and either the timeout expired before enough resources were made available, or the timeout flags were set toP_POLL
, indicating that this function shouldn't wait for additional resources to become available.
Comments
This function is equivalent to calling SysSemaphoreWaitCount()
with a count of 1. See the comments under that function for more on how this function operates.
See Also
SysSemaphoreSignal()
, SysSemaphoreWaitCount()
SysSemaphoreWaitCount Function
Purpose
Obtains one or more resources from a specified semaphore.
Declared In
SysThread.h
Prototype
status_t SysSemaphoreWaitCount ( SysHandlesemaphore
, timeoutFlags_tiTimeoutFlags
, nsecs_tiTimeout
, uint32_tcount
)
Parameters
-
→ semaphore
- ID of the semaphore from which resources are to be acquired.
-
→ iTimeoutFlags
- A value specifying how the timeout value should be interpreted. See
timeoutFlags_t
. -
→ iTimeout
- Timeout value, in nanoseconds.
-
→ count
- The number of resources to be acquired.
Returns
Returns errNone
if the specified number of resources were successfully obtained, or one of the following otherwise:
-
sysErrParamErr
-
count
is zero, orcount
exceeds the maximum count specified when the resource was created. -
sysErrTimeout
- There aren't
count
resources available, and either the timeout expired before enough resources were made available, or the timeout flags were set toP_POLL
, indicating that this function shouldn't wait for additional resources to become available.
Comments
If the available count for the specified semaphore is greater than or equal to the number of requested resources, the available count is decrement by the number of requested resources and the function returns with errNone
. If the number of available resources is less than the number of resources being requested, the calling thread is put in the WAIT state and placed in a queue associated with the semaphore. Until the request is fulfilled, the semaphore's count is not changed.
See Also
SysSemaphoreSignalCount()
, SysSemaphoreWait()
SysThreadChangePriority Function
Purpose
Change the current priority of a thread.
Declared In
SysThread.h
Prototype
status_t SysThreadChangePriority ( SysHandlethread
, uint8_tpriority
)
Parameters
-
→ thread
- The thread's identifier.
-
→ priority
- The thread's new priority. Useful thread priority values are defined under "Thread Priorities."
Returns
Returns errNone
if the thread's priority was changed, or sysErrParamErr
if either the specified priority is out of the range of allowable thread priorities, or thread
doesn't identify a known thread.
Comments
If this function is successful, the thread's new priority remains in effect until it is changed again.
This function may result in the re-ordering of the thread queues.
If SysThreadChangePriority()
is called for a thread waiting on the ready queue (including running threads) or another priority-based queue, the thread will be moved to the end of that part of the queue designated for the new priority. If the priority specified is the same as the current priority, the thread is still moved behind other threads of the same priority. Thus, a thread can relinquish its execution privileges by calling SysThreadChangePriority()
on itself and specifying its current priority.
See Also
SysThreadCreate Function
Purpose
Declared In
SysThread.h
Prototype
status_t SysThreadCreate ( SysThreadGroupHandlegroup
, const char*name
, uint8_tpriority
, uint32_tstackSize
, SysThreadEnterFunc*func
, void*argument
, SysHandle*outThread
)
Parameters
-
→ group
- The thread group of which this thread is to be a part (obtained from
SysThreadGroupCreate()
), orsysThreadNoGroup
if the thread isn't to be part of a thread group. -
→ name
- The name of the thread. The first four characters are used as the thread's ID. If a thread name isn't provided, the thread's ID is
'----'
. -
→ priority
- The requested thread priority. Valid thread priorities range from 1 to 255, with lower values having higher priority. Priority level 0 is reserved and cannot be used—applications typically have a thread priority no higher than 30. Common thread priority values are defined under "Thread Priorities."
-
→ stackSize
- The size of the thread's stack, in bytes. For a UI thread this is typically 8 KB.
-
→ func
- Pointer to the function that should initially be executed when the thread is started. See
SysThreadEnterFunc()
for the prototype of this function. -
→ argument
- Pointer to the argument block to be passed to the thread entry function identified by
func
, orNULL
if the function takes no arguments. -
← outThread
- The thread identifier. This value is owned by the newly-created thread and will be freed when the thread exits.
Returns
Returns errNone
if the thread was successfully created, or one of the following otherwise:
-
sysErrParamErr
- The
func
parameter is NULL, or thestackSize
parameter is zero. -
sysErrNoFreeResource
- The system has no free threads.
Comments
This function creates the specified thread. The new thread is put in the DORMANT state.
NOTE:
SysThreadCreate()
does not guarantee that the requested priority will be satisfied. A return value of errNone
does not guarantee that the thread has been created at requested priority. Depending upon the context in which the function was called, the actual thread priority may be lower than what was requested.
See Also
EvtCreateBackgroundThread()
, SysThreadCreateEZ()
, SysThreadGroupCreate()
, SysThreadInstallExitCallback()
, SysThreadStart()
SysThreadCreateEZ Function
Purpose
Create a new thread, using default values for the thread group, priority, and stack size.
Declared In
SysThread.h
Prototype
status_t SysThreadCreateEZ ( const char*name
, SysThreadEnterFunc*func
, void*argument
, SysHandle*outThread
)
Parameters
-
→ name
- The name of the thread. The first four characters are used as the thread's ID. If a thread name isn't provided, the thread's ID is
'----'
. -
→ func
- Pointer to the function that should initially be executed when the thread is started. See
SysThreadEnterFunc()
for the prototype of this function. -
→ argument
- Pointer to the argument block to be passed to the thread entry function identified by
func
, orNULL
if the function takes no arguments. -
← outThread
- The thread identifier. This value is owned by the newly-created thread and will be freed when the thread exits.
Returns
Returns errNone
if the thread was successfully created, or one of the following otherwise:
-
sysErrParamErr
- The
func
parameter is NULL, or thestackSize
parameter is zero. -
sysErrNoFreeResource
- The system has no free threads.
Comments
This function simply calls SysThreadCreate()
with the group
parameter set to sysThreadNoGroup
, the priority
parameter set to sysThreadPriorityNormal
, and the stackSize
parameter set to sysThreadStackUI
.
See Also
SysThreadInstallExitCallback()
, SysThreadStart()
SysThreadDelay Function
Purpose
Halts execution of the thread calling this function for a specified period of time.
Declared In
SysThread.h
Prototype
status_t SysThreadDelay ( nsecs_ttimeout
, timeoutFlags_tflags
)
Parameters
-
→ timeout
- Timeout value, in nanoseconds.
-
→ flags
- A value specifying how the timeout value should be interpreted. See
timeoutFlags_t
.
Returns
Returns errNone
if the function executed successfully, or sysErrParamErr
if flags
was set to P_WAIT_FOREVER
.
Comments
This system call temporarily halts the execution of the calling thread and makes it enter the time elapse wait state (this is one type of WAIT state). The thread halts execution for the amount of time defined by timeout
. If timeout
is 0 or if flags
is P_POLL
, the function does a yield, moving the invoking thread to the end of the priority level in the ready queue.
The time count continues even if the calling thread later enters the SUSPEND state (placing it in the WAIT-SUSPEND state).
This function returns after the calling thread has been delayed by the specified amount of time.
See Also
SysThreadChangePriority()
, SysThreadGroupWait()
, SysThreadSuspend()
SysThreadExit Function
Purpose
Causes the issuing thread to exit.
Declared In
SysThread.h
Prototype
void SysThreadExit ( void )
Parameters
Returns
Comments
A thread can exit either by calling this function or by returning from its initial entry function (specified by the func
parameter when creating the thread with SysThreadCreate()
).
This function changes the state of the specified thread to the DORMANT state. Because the thread still exists and is in the DORMANT state, it can again be started (at which point the initial entry function is executed, just as it was when the thread was originally started) by calling SysThreadStart()
.
When a thread calls this function to exit, that thread does not automatically release all of the resources (stack, memory blocks, semaphores, thread-specific data slots, and so on) which it had obtained prior to the function call. Your code is responsible for releasing all resources beforehand or, as in the case of the stack, after this function returns.
Note that if an error is detected during the execution of this function, the error is not returned to the thread which called this function.
See Also
SysThreadGroupCreate Function
Purpose
Declared In
SysThread.h
Prototype
SysThreadGroupHandle SysThreadGroupCreate ( void )
Parameters
Returns
Returns a handle to the new thread group, or sysThreadNoGroup
if the a new thread group couldn't be created.
Comments
Thread groups are a convenience provided by the operating system that allows you to wait for one or more threads to exit. Thread groups are useful for unloading libraries that have spawned their own threads. Note that destroying a thread group implicitly waits for all threads in that group to exit.
Threads must be added to a thread group at the time that they are created. Specify the thread group handle returned from SysThreadGroupCreate()
to SysThreadCreate()
in order to have the newly-created thread added to the thread group.
See Also
SysThreadCreate()
, SysThreadGroupDestroy()
, SysThreadGroupWait()
SysThreadGroupDestroy Function
Purpose
Declared In
SysThread.h
Prototype
status_t SysThreadGroupDestroy (
SysThreadGroupHandle group
)
Parameters
Returns
Comments
This function waits until all of the group's threads have exited before destroying the thread group.
See Also
SysThreadCreate()
, SysThreadGroupCreate()
, SysThreadGroupWait()
SysThreadGroupWait Function
Purpose
Wait until all of the threads in the specified thread group have exited.
Declared In
SysThread.h
Prototype
status_t SysThreadGroupWait (
SysThreadGroupHandle group
)
Parameters
Returns
See Also
SysThreadCreate()
, SysThreadGroupCreate()
, SysThreadGroupDestroy()
SysThreadInstallExitCallback Function
Purpose
Installs a function that will be executed when the current thread exits.
Declared In
SysThread.h
Prototype
status_t SysThreadInstallExitCallback ( SysThreadExitCallbackFunc*iExitCallbackP
, void*iCallbackArg
, SysThreadExitCallbackID*oThreadExitCallbackId
)
Parameters
-
→ iExitCallbackP
- Pointer to the function to be executed when the thread exits. Your callback function should have the prototype defined by
SysThreadExitCallbackFunc()
. -
→ iCallbackArg
- Pointer to the argument block needed by the exit callback function, or
NULL
if the callback requires no arguments. -
← oThreadExitCallbackId
- Pointer to a location where the ID of the exit callback function is stored, or
NULL
if you don't need this ID. You use this value in the event that you need to remove the exit callback function withSysThreadRemoveExitCallback()
.
Returns
Returns errNone
if the exit callback function was installed successfully, or sysErrNoFreeRAM
if there wasn't enough memory to allocate the thread callback structure.
Comments
A thread's exit callback functions are executed when the thread exits. You can install multiple exit callback functions for a given thread: when the thread exits, they are executed in the reverse order in which they were installed. That is, the last exit callback function installed will be the first executed.
The exit callback functions are stored in a thread-specific data (TSD) slot for the current thread.
See Also
SysThreadExit()
, SysThreadRemoveExitCallback()
SysThreadRemoveExitCallback Function
Purpose
Removes a thread exit callback function originally installed with SysThreadInstallExitCallback()
.
Declared In
SysThread.h
Prototype
status_t SysThreadRemoveExitCallback (
SysThreadExitCallbackID iThreadCallbackId
)
Parameters
-
→ iThreadCallbackId
- ID of the exit callback function returned from
SysThreadInstallExitCallback()
.
Returns
Returns errNone
if the specified exit callback function was successfully removed, or sysErrParamErr
if the supplied callback ID doesn't reference an exit callback function in the current thread's TSD (thread-specific data).
See Also
SysThreadExit()
, SysThreadInstallExitCallback()
SysThreadResume Function
Purpose
Resumes execution of a suspended thread.
Declared In
SysThread.h
Prototype
status_t SysThreadResume (
SysHandle thread
)
Parameters
Returns
Returns errNone
if the operation completed successfully (but note that because SysThreadSuspend()
can be called multiple times on a given thread, a return value of errNone
from SysThreadResume()
doesn't necessarily mean that the thread is now executing). If thread
doesn't reference a suspended thread, this function returns kalErrObjectInvalid
.
Comments
This function releases the SUSPEND state of the specified thread. Specifically, it causes the SUSPEND state to be released and the execution of the specifie prior call to SysThreadSuspend()
.
If the specified thread is in WAIT-SUSPEND state, a call to SysThreadResume()
only releases the SUSPEND state; the thread will then be in the WAIT state.
A thread cannot specify itself to this function. If a thread attempts to do so, kalErrObjectInvalid
is returned.
SysThreadResume()
only counters a single suspend request. Accordingly, if SysThreadSuspend()
has been called more than once for the thread, that thread will remain suspended even after SysThreadResume()
returns.
After resuming, the thread in the ready queue remains in the same position it was prior to suspension.
See Also
SysThreadStart()
, SysThreadSuspend()
SysThreadStart Function
Purpose
Start a thread created with SysThreadCreate()
.
Declared In
SysThread.h
Prototype
status_t SysThreadStart (
SysHandle thread
)
Parameters
-
→ thread
- Handle to the thread to be started. This is the value returned through the
outThread
parameter ofSysThreadCreate()
.
Returns
Returns errNone
if the thread was started, or kalErrObjectInvalid
if the specified thread is not in the DORMANT state.
Comments
This function changes the state of the specified thread from DORMANT to RUN/READY.
The thread priority on starting the thread is that which was specified when the thread was created. That priority may have been changed by any calls to SysThreadChangePriority()
prior to this function call.
If this function is called for a thread that is not in the DORMANT state, this function does nothing and returns kalErrObjectInvalid
. If the thread is suspended, call SysThreadResume()
instead.
See Also
SysThreadCreate()
, SysThreadResume()
SysThreadSuspend Function
Purpose
Suspend execution of a thread.
Declared In
SysThread.h
Prototype
status_t SysThreadSuspend (
SysHandle thread
)
Parameters
Returns
Returns errNone
if the thread was supended, or one of the following otherwise:
-
kalErrObjectInvalid
- The specified thread is dormant, or the specified thread is the current thread.
-
kalErrLimitReached
- This function has been called more than 255 times for the given thread.
Comments
A thread cannot suspend itself by calling this function.
The specified thread is placed into the SUSPEND state. To cause this thread to resume, call SysThreadResume()
.
If the thread specified is already in the WAIT state, it is put in the combined WAIT-SUSPEND state. If wait conditions for the thread are later fulfilled, it will enter the SUSPEND state. If you supply a thread that is in the combined WAIT-SUSPEND state to SysThreadResume()
, the thread returns to the WAIT state. The upshot of all of this is that the WAIT and SUSPEND states are independent and either one prevents execution.
If SysThreadSuspend()
is called more than once for a given thread, that thread is put in multiple SUSPEND states. This is called suspend request nesting. In this case, you must call SysThreadResume()
the same number of times that SysThreadSuspend()
was called in order to return the thread to its original state before the suspension. Note that the maximum number of times suspend requests may be nested is 255.
A thread which is suspended in addition to waiting for resources (such as waiting for a semaphore) can be allocated resources (such as semaphore counts) based on the same conditions as threads which are not suspended. Even when suspended, the allocation of resources is not delayed in any way. Conditions concerning resource allocation and release of the wait state remain unchanged. In other words, the SUSPEND state is completely independent of other processing and thread states.
If you need to delay the allocation of resources to a thread which is suspended, the use SysThreadChangePriority()
in conjunction with SysThreadSuspend()
and SysThreadResume()
.
See Also
SysThreadDelay()
, SysThreadExit()
, SysThreadResume()
SysTSDAllocate Function
Purpose
Allocates a new thread-specific data (TSD) slot.
Declared In
SysThread.h
Prototype
status_t SysTSDAllocate ( SysTSDSlotID*oTSDSlot
, SysTSDDestructorFunc*iDestructor
, uint32_tiName
)
Parameters
-
← oTSDSlot
- TSD slot identifier, set upon successful allocation of the slot.
-
→ iDestructor
- Pointer to a destructor function that is called to clean up any data associated with the slot when the thread exits. This function is optional; pass
NULL
if you don't want to use a destructor. The destructor function should have the prototype defined bySysTSDDestructorFunc()
. -
→ iName
- TSD slot name (note that this is a 32-bit value). Pass sysTSDAnonymous if you don't care about the slot name (see the Comments section, below, for more on why you might care about the TSD slot name).
Returns
Returns errNone
if the operation completed successfully, or kalErrLimitReached
if the thread already has the maximum number of TSD slots allocated for it.
Comments
Calling SysTSDAllocate()
more than once with the same slot name simply updates the destructor function pointer; the same TSD slot identifer is returned each time. If you don't need to update the TSD slot's destructor function pointer, you can pass sysTSDAnonymous
for the TSD slot name. This simply allocates the next available slot, sets its destructor pointer to the supplied value, and returns the slot's identifier.
See Also
SysTSDFree()
, SysTSDGet()
, SysTSDSet()
SysTSDFree Function
Purpose
Deallocates a previously created thread-specific data (TSD) slot.
Declared In
SysThread.h
Prototype
status_t SysTSDFree (
SysTSDSlotID tsdslot
)
Parameters
-
→ tsdslot
- TSD slot identifier obtained from
SysTSDAllocate()
.
Returns
Returns errNone
if the TSD slot was successfully freed, or sysErrParamErr
if tsdslot
doesn't reference a valid slot.
Comments
Applications should not normally make use of this function. A thread's TSD slots are deallocated automatically when the thread exits, so applications generally don't need to free the slots explicitly.
See Also
SysThreadExit()
, SysTSDAllocate()
, SysTSDDestructorFunc()
SysTSDGet Function
Purpose
Get the contents of a specified thread-specific data (TSD) slot.
Declared In
SysThread.h
Prototype
void *SysTSDGet (
SysTSDSlotID tsdslot
)
Parameters
-
→ tsdslot
- TSD slot identifier obtained from
SysTSDAllocate()
.
Returns
Returns the slot contents, or 0 if tsdslot
doesn't reference a valid TSD slot.
See Also
SysTSDSet Function
Purpose
Set the contents of a specified thread-specific data (TSD) slot.
Declared In
SysThread.h
Prototype
void SysTSDSet ( SysTSDSlotIDtsdslot
, void*iValue
)
Parameters
-
→ tsdslot
- TSD slot identifier obtained from
SysTSDAllocate()
. -
→ iValue
- A 32-bit value to be placed into the specified TSD slot.
Returns
Comments
This function does nothing if tsdslot
doesn't reference a valid TSD slot.
See Also
Application-Defined Functions
SysThreadEnterFunc Function
Purpose
Prototype of a thread entry function.
Declared In
SysThread.h
Prototype
void (
SysThreadEnterFunc
) (
void *param
)
Parameters
-
→ param
- The parameter pointer originally supplied to the
SysThreadCreate()
orSysThreadCreateEZ()
function
Returns
See Also
SysThreadExitCallbackFunc Function
Purpose
Prototype of a thread exit callback function.
Declared In
SysThread.h
Prototype
void (
SysThreadExitCallbackFunc
) (
void *param
)
Parameters
-
→ param
- The parameter pointer originally supplied to the
SysThreadInstallExitCallback()
function
Returns
See Also
SysTSDDestructorFunc Function
Purpose
Prototype of a thread-specific data (TSD) slot destructor function.
Declared In
SysThread.h
Prototype
void (
SysTSDDestructorFunc
) (
void *param
)
Parameters
-
→ param
- The contents of the TSD slot. This is the value supplied in the most recent call to
SysTSDSet()
for the slot.
Returns
Comments
The slot's destructor function—specified when the TSD slot was allocated with SysTSDAllocate()
—is called to clean up any data associated with the slot when the thread exits. This function is only called for a slot if the slot contents are non-NULL
. Slots are initialized to NULL
when they are allocated, so if you never call SysTSDSet()
for a slot, when the thread exits the slot destructor isn't called for that slot.