SysThread.h File Reference

Detailed Description

Basic APIs for working with threads.

#include <PalmTypes.h>

Go to the source code of this file.

Lightweight Condition Variables

#define sysConditionVariableInitializer   0

The value to use when initializing a SysConditionVariableType.

typedef void * SysConditionVariableType

The value to use when initializing a SysConditionVariableType.

Lightweight Locking

#define sysCriticalSectionInitializer   NULL

The value to use when initializing a SysCriticalSectionType.

typedef void * SysCriticalSectionType

The value to use when initializing a SysCriticalSectionType.

Thread Groups

These are a convenience provided by the system library to wait for one or more threads to exit. It is 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.

#define sysThreadNoGroup   NULL

typedef SysThreadGroupType * SysThreadGroupHandle

typedef SysThreadGroupTag SysThreadGroupType

SysThreadGroupHandle SysThreadGroupCreate (void)

status_t SysThreadGroupDestroy (SysThreadGroupHandle group)

status_t SysThreadGroupWait (SysThreadGroupHandle group)

Thread Creation and Management

typedef void( SysThreadEnterFunc )(void *)

Create a new thread.

SysHandle SysCurrentThread (void)

Return the handle for the calling thread.

status_t SysThreadChangePriority (SysHandle thread, uint8_t priority)

Change a thread's priority.

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

Like SysThreadCreateEZ(), but with more stuff.

status_t SysThreadCreateEZ (const char *name, SysThreadEnterFunc *func, void *argument, SysHandle *outThread)

Create a new thread.

status_t SysThreadDelay (nsecs_t timeout, timeoutFlags_t flags)

Go to sleep for the given amount of time.

void SysThreadExit (void)

Call this function to have the current thread exit.

int SysThreadKill (SysHandle thread, int signo)

Deliver a POSIX signal to a thread.

status_t SysThreadStart (SysHandle thread)

Start a thread that was created above with SysThreadCreate() or SysThreadCreateEZ().

Thread Finalizers

typedef void( SysThreadExitCallbackFunc )(void *)

typedef uint32_t SysThreadExitCallbackID

status_t SysThreadInstallExitCallback (SysThreadExitCallbackFunc *iExitCallbackP, void *iCallbackArg, SysThreadExitCallbackID *oThreadExitCallbackId)

status_t SysThreadRemoveExitCallback (SysThreadExitCallbackID iThreadCallbackId)

Thread Specific Data

typedef void( SysTSDDestructorFunc )(void *)

typedef uint32_t SysTSDSlotID

enum { sysTSDAnonymous = 0 }

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

status_t SysTSDFree (SysTSDSlotID tsdslot)

void * SysTSDGet (SysTSDSlotID tsdslot)

void SysTSDSet (SysTSDSlotID tsdslot, void *iValue)

Counting Semaphores

enum { sysSemaphoreMaxCount = 0xffff }

status_t SysSemaphoreCreate (uint32_t initialCount, uint32_t maxCount, uint32_t flags, SysHandle *outSemaphore)

status_t SysSemaphoreCreateEZ (uint32_t initialCount, SysHandle *outSemaphore)

status_t SysSemaphoreDestroy (SysHandle semaphore)

status_t SysSemaphoreSignal (SysHandle semaphore)

status_t SysSemaphoreSignalCount (SysHandle semaphore, uint32_t count)

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

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

Atomic Operations

int32_t SysAtomicAdd32 (int32_t volatile *ioOperandP, int32_t iAddend)

uint32_t SysAtomicAnd32 (uint32_t volatile *ioOperandP, uint32_t iValue)

uint32_t SysAtomicCompareAndSwap32 (uint32_t volatile *ioOperandP, uint32_t iOldValue, uint32_t iNewValue)

int32_t SysAtomicDec32 (int32_t volatile *ioOperandP)

int32_t SysAtomicInc32 (int32_t volatile *ioOperandP)

uint32_t SysAtomicOr32 (uint32_t volatile *ioOperandP, uint32_t iValue)

Miscellaneous

nsecs_t SysGetRunTime (void)

Return the amount of time (in nanoseconds) the system has been running.

Typedefs

typedef uint16_t timeoutFlags_t

a combination of timeoutFlagsEnum_t and timebase_t flags

Enumerations

enum {
  sysThreadPriorityLowered = 100, sysThreadPriorityNormal = 80, sysThreadPriorityBestApp = 80, sysThreadPriorityRaised = 70,
  sysThreadPriorityTransaction = 65, sysThreadPriorityDisplay = 60, sysThreadPriorityUrgentDisplay = 50, sysThreadPriorityRealTime = 40,
  sysThreadPriorityBestUser = 30, sysThreadPriorityBestSystem = 5, sysThreadPriorityLow = sysThreadPriorityLowered, sysThreadPriorityHigh = sysThreadPriorityRealTime
}

Standard thread priority levels. More...

enum { sysThreadStackBasic = 4*1024, sysThreadStackUI = 8*1024 }

Standard thread stack sizes. More...

enum timeoutFlagsEnum_t { B_WAIT_FOREVER = 0x0000, B_POLL = 0x0300, B_RELATIVE_TIMEOUT = 0x0100, B_ABSOLUTE_TIMEOUT = 0x0200 }

Timeout flags. More...

Define Documentation

#define sysConditionVariableInitializer 0

The value to use when initializing a SysConditionVariableType.

#define sysCriticalSectionInitializer NULL

The value to use when initializing a SysCriticalSectionType.

#define sysThreadNoGroup NULL

Typedef Documentation

typedef void* SysConditionVariableType

The value to use when initializing a SysConditionVariableType.

typedef void* SysCriticalSectionType

The value to use when initializing a SysCriticalSectionType.

typedef void( SysThreadEnterFunc)(void *)

Create a new thread.

Parameters:

[in] name First four letters are used for thread ID.

[in] func Entry point of thread.

[in] argument Data passed to above.

[out] outThtread Returned thread handle.

The thread's priority is sysThreadPriorityNormal and its stack size is sysThreadStackUI.
The returned SysHandle is owned by the newly created thread, and we be freed when that thread exits. It is the same SysHandle as the thread uses for its local identity in its TSD, so you can use this as a unique identity for the thread.

typedef void( SysThreadExitCallbackFunc)(void *)

typedef uint32_t SysThreadExitCallbackID

typedef SysThreadGroupType* SysThreadGroupHandle

typedef struct SysThreadGroupTag SysThreadGroupType

typedef void( SysTSDDestructorFunc)(void *)

typedef uint32_t SysTSDSlotID

Enumeration Type Documentation

anonymous enum

Enumerator:

sysTSDAnonymous

anonymous enum

Enumerator:

sysSemaphoreMaxCount

Function Documentation

int32_t SysAtomicAdd32 ( int32_t volatile * ioOperandP,

int32_t iAddend

) [inline]

uint32_t SysAtomicAnd32 ( uint32_t volatile * ioOperandP,

uint32_t iValue

) [inline]

uint32_t SysAtomicCompareAndSwap32 ( uint32_t volatile * ioOperandP,

uint32_t iOldValue,

uint32_t iNewValue

) [inline]

int32_t SysAtomicDec32 ( int32_t volatile * ioOperandP )

int32_t SysAtomicInc32 ( int32_t volatile * ioOperandP )

uint32_t SysAtomicOr32 ( uint32_t volatile * ioOperandP,

uint32_t iValue

) [inline]

SysHandle SysCurrentThread ( void )

Return the handle for the calling thread.

nsecs_t SysGetRunTime ( void )

Return the amount of time (in nanoseconds) the system has been running.
This time does not include time during which the device is asleep.

status_t SysSemaphoreCreate ( uint32_t initialCount,

uint32_t maxCount,

uint32_t flags,

SysHandle * outSemaphore

)

status_t SysSemaphoreCreateEZ ( uint32_t initialCount,

SysHandle * outSemaphore

)

status_t SysSemaphoreDestroy ( SysHandle semaphore )

status_t SysSemaphoreSignal ( SysHandle semaphore )

status_t SysSemaphoreSignalCount ( SysHandle semaphore,

uint32_t count

)

status_t SysSemaphoreWait ( SysHandle semaphore,

timeoutFlags_t iTimeoutFlags,

nsecs_t iTimeout

)

status_t SysSemaphoreWaitCount ( SysHandle semaphore,

timeoutFlags_t iTimeoutFlags,

nsecs_t iTimeout,

uint32_t count

)

status_t SysThreadChangePriority ( SysHandle thread,

uint8_t priority

)

Change a thread's priority.

status_t SysThreadCreate ( SysThreadGroupHandle group,

const char * name,

uint8_t priority,

uint32_t stackSize,

SysThreadEnterFunc * func,

void * argument,

SysHandle * outThread

)

Like SysThreadCreateEZ(), but with more stuff.

Parameters:

[in] group Thread group, normally sysThreadNoGroup.

[in] name First four letters are used for thread ID.

[in] priority Pick one of the thread priority constants.

[in] stackSize Bytes available for the thread's stack.

[in] func Entry point of thread.

[in] argument Data passed to above.

[out] outThtread Returned thread handle.

status_t SysThreadCreateEZ ( const char * name,

SysThreadEnterFunc * func,

void * argument,

SysHandle * outThread

)

Create a new thread.

Parameters:

[in] name First four letters are used for thread ID.

[in] func Entry point of thread.

[in] argument Data passed to above.

[out] outThtread Returned thread handle.

The thread's priority is sysThreadPriorityNormal and its stack size is sysThreadStackUI.
The returned SysHandle is owned by the newly created thread, and we be freed when that thread exits. It is the same SysHandle as the thread uses for its local identity in its TSD, so you can use this as a unique identity for the thread.

status_t SysThreadDelay ( nsecs_t timeout,

timeoutFlags_t flags

)

Go to sleep for the given amount of time.

void SysThreadExit ( void )

Call this function to have the current thread exit.
The thread MUST have been created with SysThreadCreate().

SysThreadGroupHandle SysThreadGroupCreate ( void )

status_t SysThreadGroupDestroy ( SysThreadGroupHandle group )

status_t SysThreadGroupWait ( SysThreadGroupHandle group )

status_t SysThreadInstallExitCallback ( SysThreadExitCallbackFunc * iExitCallbackP,

void * iCallbackArg,

SysThreadExitCallbackID * oThreadExitCallbackId

)

int SysThreadKill ( SysHandle thread,

int signo

)

Deliver a POSIX signal to a thread.

Parameters:

[in] thread Thread handle as returned by the creation function.

[in] signo Signal number

Returns a status value the same as kill().

status_t SysThreadRemoveExitCallback ( SysThreadExitCallbackID iThreadCallbackId )

status_t SysThreadStart ( SysHandle thread )

Start a thread that was created above with SysThreadCreate() or SysThreadCreateEZ().

Parameters:

[in] thread Thread handle as returned by the creation function.

If this function fails, the thread handle and all associated resources will be deallocated.

status_t SysTSDAllocate ( SysTSDSlotID * oTSDSlot,

SysTSDDestructorFunc * iDestructor,

uint32_t iName

)

status_t SysTSDFree ( SysTSDSlotID tsdslot )

void* SysTSDGet ( SysTSDSlotID tsdslot )

void SysTSDSet ( SysTSDSlotID tsdslot,

void * iValue

)


Lightweight Condition Variables
#define	sysConditionVariableInitializer 0
	The value to use when initializing a SysConditionVariableType.
typedef void *	SysConditionVariableType
	The value to use when initializing a SysConditionVariableType.
Lightweight Locking
#define	sysCriticalSectionInitializer NULL
	The value to use when initializing a SysCriticalSectionType.
typedef void *	SysCriticalSectionType
	The value to use when initializing a SysCriticalSectionType.
Thread Groups
These are a convenience provided by the system library to wait for one or more threads to exit. It is 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.
#define	sysThreadNoGroup NULL
typedef SysThreadGroupType *	SysThreadGroupHandle
typedef SysThreadGroupTag	SysThreadGroupType
SysThreadGroupHandle	SysThreadGroupCreate (void)
status_t	SysThreadGroupDestroy (SysThreadGroupHandle group)
status_t	SysThreadGroupWait (SysThreadGroupHandle group)
Thread Creation and Management
typedef void(	SysThreadEnterFunc )(void *)
	Create a new thread.
SysHandle	SysCurrentThread (void)
	Return the handle for the calling thread.
status_t	SysThreadChangePriority (SysHandle thread, uint8_t priority)
	Change a thread's priority.
status_t	SysThreadCreate (SysThreadGroupHandle group, const char name, uint8_t priority, uint32_t stackSize, SysThreadEnterFunc func, void argument, SysHandle outThread)
	Like SysThreadCreateEZ(), but with more stuff.
status_t	SysThreadCreateEZ (const char name, SysThreadEnterFunc func, void argument, SysHandle outThread)
	Create a new thread.
status_t	SysThreadDelay (nsecs_t timeout, timeoutFlags_t flags)
	Go to sleep for the given amount of time.
void	SysThreadExit (void)
	Call this function to have the current thread exit.
int	SysThreadKill (SysHandle thread, int signo)
	Deliver a POSIX signal to a thread.
status_t	SysThreadStart (SysHandle thread)
	Start a thread that was created above with SysThreadCreate() or SysThreadCreateEZ().
Thread Finalizers
typedef void(	SysThreadExitCallbackFunc )(void *)
typedef uint32_t	SysThreadExitCallbackID
status_t	SysThreadInstallExitCallback (SysThreadExitCallbackFunc iExitCallbackP, void iCallbackArg, SysThreadExitCallbackID *oThreadExitCallbackId)
status_t	SysThreadRemoveExitCallback (SysThreadExitCallbackID iThreadCallbackId)
Thread Specific Data
typedef void(	SysTSDDestructorFunc )(void *)
typedef uint32_t	SysTSDSlotID
enum	{ sysTSDAnonymous = 0 }
status_t	SysTSDAllocate (SysTSDSlotID oTSDSlot, SysTSDDestructorFunc iDestructor, uint32_t iName)
status_t	SysTSDFree (SysTSDSlotID tsdslot)
void *	SysTSDGet (SysTSDSlotID tsdslot)
void	SysTSDSet (SysTSDSlotID tsdslot, void *iValue)
Counting Semaphores
enum	{ sysSemaphoreMaxCount = 0xffff }
status_t	SysSemaphoreCreate (uint32_t initialCount, uint32_t maxCount, uint32_t flags, SysHandle *outSemaphore)
status_t	SysSemaphoreCreateEZ (uint32_t initialCount, SysHandle *outSemaphore)
status_t	SysSemaphoreDestroy (SysHandle semaphore)
status_t	SysSemaphoreSignal (SysHandle semaphore)
status_t	SysSemaphoreSignalCount (SysHandle semaphore, uint32_t count)
status_t	SysSemaphoreWait (SysHandle semaphore, timeoutFlags_t iTimeoutFlags, nsecs_t iTimeout)
status_t	SysSemaphoreWaitCount (SysHandle semaphore, timeoutFlags_t iTimeoutFlags, nsecs_t iTimeout, uint32_t count)
Atomic Operations
int32_t	SysAtomicAdd32 (int32_t volatile *ioOperandP, int32_t iAddend)
uint32_t	SysAtomicAnd32 (uint32_t volatile *ioOperandP, uint32_t iValue)
uint32_t	SysAtomicCompareAndSwap32 (uint32_t volatile *ioOperandP, uint32_t iOldValue, uint32_t iNewValue)
int32_t	SysAtomicDec32 (int32_t volatile *ioOperandP)
int32_t	SysAtomicInc32 (int32_t volatile *ioOperandP)
uint32_t	SysAtomicOr32 (uint32_t volatile *ioOperandP, uint32_t iValue)
Miscellaneous
nsecs_t	SysGetRunTime (void)
	Return the amount of time (in nanoseconds) the system has been running.
Typedefs
typedef uint16_t	timeoutFlags_t
	a combination of timeoutFlagsEnum_t and timebase_t flags
Enumerations
enum	{ sysThreadPriorityLowered = 100, sysThreadPriorityNormal = 80, sysThreadPriorityBestApp = 80, sysThreadPriorityRaised = 70, sysThreadPriorityTransaction = 65, sysThreadPriorityDisplay = 60, sysThreadPriorityUrgentDisplay = 50, sysThreadPriorityRealTime = 40, sysThreadPriorityBestUser = 30, sysThreadPriorityBestSystem = 5, sysThreadPriorityLow = sysThreadPriorityLowered, sysThreadPriorityHigh = sysThreadPriorityRealTime }
	Standard thread priority levels. More...
enum	{ sysThreadStackBasic = 41024, sysThreadStackUI = 81024 }
	Standard thread stack sizes. More...
enum	timeoutFlagsEnum_t { B_WAIT_FOREVER = 0x0000, B_POLL = 0x0300, B_RELATIVE_TIMEOUT = 0x0100, B_ABSOLUTE_TIMEOUT = 0x0200 }
	Timeout flags. More...