Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

36    SysThread

System Management

Exploring Palm OS®

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 ^TOP^

SysConditionVariableType Typedef ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

Purpose

Handle to a thread group.

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 ^TOP^

Purpose

Identifier for an internal structure that represents a thread group.

Declared In

SysThread.h

Prototype

struct SysThreadGroupTag

SysThreadGroupType Struct ^TOP^

Purpose

Type definition for an internal structure that represents a thread group.

Declared In

SysThread.h

Prototype

typedef struct SysThreadGroupTag 
SysThreadGroupType

SysTSDSlotID Typedef ^TOP^

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 ^TOP^

Thread Priorities ^TOP^

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 ^TOP^

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 to SysThreadCreate() if you don't want the thread you are creating to be part of a thread group. Note that SysThreadCreateEZ() only creates threads that are not part of a thread group: it calls SysThreadCreate() and passes a value of sysThreadNoGroup for the group 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 ^TOP^

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 ^TOP^

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() or SysSemaphoreCreateEZ().

timeoutFlags_t Typedef ^TOP^

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 ^TOP^

SysAtomicAdd32 Function ^TOP^

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_t iAddend
)

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 ^TOP^

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_t iValue
)

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 ^TOP^

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_t iOldValue,
   uint32_t iNewValue
)

Parameters

ioOperandP
Pointer to a 32-bit quantity against which iOldValue is to be compared. Upon return the indicated memory location is set to iNewValue if *ioOperandP proved equal to iOldValue.
iOldValue
Value against which *ioOperandP is to be compared.
iNewValue
Value to be stored in *ioOperandP if *ioOperandP is equal to iOldValue.

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 ^TOP^

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_t iValue
)

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 ^TOP^

Purpose

Cause all threads waiting on a specified condition variable to continue.

Declared In

SysThread.h

Prototype

void SysConditionVariableBroadcast (
   SysConditionVariableType *iCV
)

Parameters

iCV
Pointer to the condition variable upon which waiting threads are to be released.

Returns

Nothing.

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 ^TOP^

Purpose

Transition a condition variable from opened to closed.

Declared In

SysThread.h

Prototype

void SysConditionVariableClose (
   SysConditionVariableType *iCV
)

Parameters

iCV
Pointer to the condition variable that is to be closed.

Returns

Nothing.

Comments

If the condition variable is not open when this function is called, it is left as-is.

See Also

SysConditionVariableOpen(), SysConditionVariableWait()

SysConditionVariableOpen Function ^TOP^

Purpose

Transition a condition variable from closed to opened.

Declared In

SysThread.h

Prototype

void SysConditionVariableOpen (
   SysConditionVariableType *iCV
)

Parameters

iCV
Pointer to the condition variable that is to be opened.

Returns

Nothing.

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 ^TOP^

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

Nothing.

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 ^TOP^

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 to sysCriticalSectionInitializer.

Returns

Nothing.

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()

SysCriticalSectionExit Function ^TOP^

Purpose

Release a critical section.

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

Nothing.

Comments

Call this function at the end of the critical section, thereby allowing another process to enter the critical section.

See Also

SysCriticalSectionEnter()

SysCurrentThread Function ^TOP^

Purpose

Return the identity of the current thread.

Declared In

SysThread.h

Prototype

SysHandle SysCurrentThread (
   void
)

Parameters

None.

Returns

Returns the thread ID of the current thread.

SysGetRunTime Function ^TOP^

Purpose

Get the length of time since last reset, in nanoseconds.

Declared In

SysThread.h

Prototype

nsecs_t SysGetRunTime (
   void
)

Parameters

None.

Returns

Returns the amount of time, in nanoseconds, since the last reset.

SysSemaphoreCreate Function ^TOP^

Purpose

Create a new counting semaphore with the specified initial count and maximum count values.

Declared In

SysThread.h

Prototype

status_t SysSemaphoreCreate (
   uint32_t initialCount,
   uint32_t maxCount,
   uint32_t flags,
   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 or maxCount exceeds sysSemaphoreMaxCount.
sysErrParamErr
initialCount exceeds maxCount.
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 ^TOP^

Purpose

Creates a new counting semaphore with a maximum count value of sysSemaphoreMaxCount (65535).

Declared In

SysThread.h

Prototype

status_t SysSemaphoreCreateEZ (
   uint32_t initialCount,
   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 exceeds sysSemaphoreMaxCount.
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 ^TOP^

Purpose

Destroy a counting semaphore.

Declared In

SysThread.h

Prototype

status_t SysSemaphoreDestroy (
   SysHandle semaphore
)

Parameters

semaphore
ID of the semaphore to be destroyed.

Returns

Always returns errNone.

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 ^TOP^

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

semaphore
ID of the semaphore to which resources are to be released.

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 ^TOP^

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 (
   SysHandle semaphore,
   uint32_t count
)

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 ^TOP^

Purpose

Obtains a single resource from a specified semaphore.

Declared In

SysThread.h

Prototype

status_t SysSemaphoreWait (
   SysHandle semaphore,
   timeoutFlags_t iTimeoutFlags,
   nsecs_t iTimeout
)

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 to P_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 ^TOP^

Purpose

Obtains one or more resources from a specified semaphore.

Declared In

SysThread.h

Prototype

status_t SysSemaphoreWaitCount (
   SysHandle semaphore,
   timeoutFlags_t iTimeoutFlags,
   nsecs_t iTimeout,
   uint32_t count
)

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, or count 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 to P_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 ^TOP^

Purpose

Change the current priority of a thread.

Declared In

SysThread.h

Prototype

status_t SysThreadChangePriority (
   SysHandle thread,
   uint8_t priority
)

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()

SysThreadCreate Function ^TOP^

Purpose

Create a new thread.

Declared In

SysThread.h

Prototype

status_t SysThreadCreate (
   SysThreadGroupHandle group,
   const char *name,
   uint8_t priority,
   uint32_t stackSize,
   SysThreadEnterFunc *func,
   void *argument,
   SysHandle *outThread
)

Parameters

group
The thread group of which this thread is to be a part (obtained from SysThreadGroupCreate()), or sysThreadNoGroup 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, or NULL 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 the stackSize 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 ^TOP^

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, or NULL 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 the stackSize 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 ^TOP^

Purpose

Halts execution of the thread calling this function for a specified period of time.

Declared In

SysThread.h

Prototype

status_t SysThreadDelay (
   nsecs_t timeout,
   timeoutFlags_t flags
)

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 ^TOP^

Purpose

Causes the issuing thread to exit.

Declared In

SysThread.h

Prototype

void SysThreadExit (
   void
)

Parameters

None.

Returns

Nothing.

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

SysThreadSuspend()

SysThreadGroupCreate Function ^TOP^

Purpose

Create a new thread group.

Declared In

SysThread.h

Prototype

SysThreadGroupHandle SysThreadGroupCreate (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Destroy a thread group.

Declared In

SysThread.h

Prototype

status_t SysThreadGroupDestroy (
   SysThreadGroupHandle group
)

Parameters

group
Handle to the thread group to be destroyed.

Returns

Always returns errNone.

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 ^TOP^

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

group
Handle to the thread group upon which to wait.

Returns

Always returns errNone.

See Also

SysThreadCreate(), SysThreadGroupCreate(), SysThreadGroupDestroy()

SysThreadInstallExitCallback Function ^TOP^

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 with SysThreadRemoveExitCallback().

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 ^TOP^

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 ^TOP^

Purpose

Resumes execution of a suspended thread.

Declared In

SysThread.h

Prototype

status_t SysThreadResume (
   SysHandle thread
)

Parameters

thread
The ID of the thread that is to resume execution.

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 ^TOP^

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 of SysThreadCreate().

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 ^TOP^

Purpose

Suspend execution of a thread.

Declared In

SysThread.h

Prototype

status_t SysThreadSuspend (
   SysHandle thread
)

Parameters

thread
The thread ID of the thread to suspend.

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 ^TOP^

Purpose

Allocates a new thread-specific data (TSD) slot.

Declared In

SysThread.h

Prototype

status_t SysTSDAllocate (
   SysTSDSlotID *oTSDSlot,
   SysTSDDestructorFunc *iDestructor,
   uint32_t iName
)

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 by SysTSDDestructorFunc().
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 ^TOP^

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 ^TOP^

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

SysTSDAllocate(), SysTSDSet()

SysTSDSet Function ^TOP^

Purpose

Set the contents of a specified thread-specific data (TSD) slot.

Declared In

SysThread.h

Prototype

void SysTSDSet (
   SysTSDSlotID tsdslot,
   void *iValue
)

Parameters

tsdslot
TSD slot identifier obtained from SysTSDAllocate().
iValue
A 32-bit value to be placed into the specified TSD slot.

Returns

Nothing.

Comments

This function does nothing if tsdslot doesn't reference a valid TSD slot.

See Also

SysTSDAllocate(), SysTSDGet()

Application-Defined Functions ^TOP^

SysThreadEnterFunc Function ^TOP^

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() or SysThreadCreateEZ() function

Returns

Nothing.

See Also

SysThreadExitCallbackFunc()

SysThreadExitCallbackFunc Function ^TOP^

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

Nothing.

See Also

SysThreadEnterFunc()

SysTSDDestructorFunc Function ^TOP^

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

Nothing.

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.

See Also

SysTSDAllocate()