X11 Work Bench Toolkit  1.0
Threads and Synchronization

Functions

WB_THREAD_KEY WBThreadAllocLocal (void)
 Allocate 'thread local' storage. More...
 
void WBThreadFreeLocal (WB_THREAD_KEY keyVal)
 Free 'thread local' storage allocated by WBThreadAllocLocal() More...
 
void * WBThreadGetLocal (WB_THREAD_KEY keyVal)
 Get 'thread local' data identified by 'keyVal'. More...
 
void WBThreadSetLocal (WB_THREAD_KEY keyVal, void *pValue)
 Get 'thread local' data identified by 'keyVal'. More...
 
WB_THREAD WBThreadGetCurrent (void)
 Get 'current thread' identifier. More...
 
WB_THREAD WBThreadCreate (void *(*function)(void *), void *pParam)
 Create a new thread, returning its WB_THREAD identifier. More...
 
void * WBThreadWait (WB_THREAD hThread)
 Wait for a specified threat to exit. More...
 
int WBThreadRunning (WB_THREAD hThread)
 Determine whether a thread is running (can be suspended) More...
 
void WBThreadExit (void *pRval)
 Exit the current thread immediately, specifying return code. More...
 
void WBThreadClose (WB_THREAD hThread)
 Close the specified WB_THREAD identifier. More...
 
int WBCondCreate (WB_COND *pCond)
 Create a signallable condition. More...
 
int WBMutexCreate (WB_MUTEX *pMtx)
 Create a lockable mutex. More...
 
void WBCondFree (WB_COND *pCond)
 Free a signallable condition. More...
 
void WBMutexFree (WB_MUTEX *pMtx)
 Free a lockable mutex. More...
 
int WBMutexLock (WB_MUTEX *pMtx, int nTimeout)
 Wait for and lock a mutex, blocking until it is available. More...
 
int WBMutexUnlock (WB_MUTEX *pMtx)
 Unlock a previously locked mutex. More...
 
int WBCondSignal (WB_COND *pCond)
 Signal a condition (event) More...
 
int WBCondWait (WB_COND *pCond, int nTimeout)
 Wait for a signal on a condition (event) More...
 
int WBCondWaitMutex (WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout)
 Wait for a signal on a condition (event) More...
 
WB_UINT32 WBInterlockedDecrement (volatile WB_UINT32 *pValue)
 Interlocked 'atomic' decrement of an unsigned integer. More...
 
WB_UINT32 WBInterlockedIncrement (volatile WB_UINT32 *pValue)
 Interlocked 'atomic' increment of an unsigned integer. More...
 
WB_UINT32 WBInterlockedExchange (volatile WB_UINT32 *pValue, WB_UINT32 nNewVal)
 Interlocked 'atomic' exchange of an unsigned integer with a specified value. More...
 
WB_UINT32 WBInterlockedRead (volatile WB_UINT32 *pValue)
 Interlocked 'atomic' read of an unsigned integer. More...
 

Detailed Description

These functions and data types help to abstract the various thread and synchronization functions that are necessary to properly implement threads.

Function Documentation

int WBCondCreate ( WB_COND pCond)

Create a signallable condition.

Parameters
pCondA pointer to the WB_COND that will be created (could be a struct or just a pointer)
Returns
A zero value if successful; non-zero on error

Use this function to create a 'condition' that can be signaled using WBCondSignal()
This is roughly the equivalent of an 'Event' object on MS Windows

Header File: platform_helper.h

Definition at line 3594 of file platform_helper.c.

void WBCondFree ( WB_COND pCond)

Free a signallable condition.

Parameters
pConda pointer to the WB_COND signallable condition

Use this function to free a WB_COND that was previously allocated with WBCondCreate()

Header File: platform_helper.h

Definition at line 3650 of file platform_helper.c.

int WBCondSignal ( WB_COND pCond)

Signal a condition (event)

Parameters
pConda pointer to the WB_COND condition object
Returns
A zero if the signal succeeded, or non-zero on error

This function signals a condition so that a waiting process will 'wake up' see WBCondWait() and WBCondWaitMutex()

Header File: platform_helper.h

Definition at line 3732 of file platform_helper.c.

int WBCondWait ( WB_COND pCond,
int  nTimeout 
)

Wait for a signal on a condition (event)

Parameters
pConda poiner to the WB_COND condition object
nTimeoutthe timeout (in microseconds), or a value < 0 to indicate 'INFINITE'
Returns
A zero if the condition was triggered, a value > 0 on timeout, or a value < 0 on error

This function waits up to a specified time (in microseconds), or indefinitely if the specified wait time is negative, until the condition object 'hCond' has been signaled. See WBCondSignal()

Header File: platform_helper.h

Definition at line 3748 of file platform_helper.c.

int WBCondWaitMutex ( WB_COND pCond,
WB_MUTEX pMtx,
int  nTimeout 
)

Wait for a signal on a condition (event)

Parameters
pConda pointer to the WB_COND condition object
pMtxa pointer to a locked WB_MUTEX object
nTimeoutthe timeout (in microseconds), or a value < 0 to indicate 'INFINITE'
Returns
A zero if the condition was triggered, a value > 0 on timeout, or a value < 0 on error

This function waits up to a specified time (in microseconds), or indefinitely if the specified wait time is negative, until the condition object 'hCond' has been signaled. See WBCondSignal()
Additionally, when the waiting process begins, the WB_MUTEX referenced by 'hMtx' will be unlocked, until the condition referenced by 'hCond' has been signaled, or the timeout period has been exceeded. At that point, the mutex 'hMtx' will be re-locked (waiting indefinitely for the lock to be successful)
Upon return, 'hMtx' will be locked again by the calling thread. 'hMtx' must be already locked before calling this function. It will remain unlocked during the wait state.

Header File: platform_helper.h

Definition at line 3821 of file platform_helper.c.

WB_UINT32 WBInterlockedDecrement ( volatile WB_UINT32 pValue)

Interlocked 'atomic' decrement of an unsigned integer.

Parameters
pValue- a pointer to an 'unsigned int' to be decremented atomically. Must be a valid pointer
Returns
The new value stored in 'pValue' after decrementing

This function performs an interlocked 'atomic' decrement of an unsigned integer, guaranteeing that at the time the value is decremented, no other thread is allowed to read or modify the value until the function returns.

Header File: platform_helper.h

WB_UINT32 WBInterlockedExchange ( volatile WB_UINT32 pValue,
WB_UINT32  nNewVal 
)

Interlocked 'atomic' exchange of an unsigned integer with a specified value.

Parameters
pValue- a pointer to an 'unsigned int' to be exchanged with the specified value. Must be a valid pointer.
nNewVal- the new value to assign to 'pValue' atomically
Returns
The old value previously stored in 'pValue' after exchanging

This function performs an interlocked 'atomic' assignment of an unsigned integer, guaranteeing that at the time the value is assigned, no other thread is allowed to read or modify the value until the function returns. The previous value is returned by the function, effectively 'exchanging' the value with one that you specify.

Header File: platform_helper.h

WB_UINT32 WBInterlockedIncrement ( volatile WB_UINT32 pValue)

Interlocked 'atomic' increment of an unsigned integer.

Parameters
pValue- a pointer to an 'unsigned int' to be incremented atomically. Must be a valid pointer
Returns
The new value stored in 'pValue' after incrementing

This function performs an interlocked 'atomic' increment of an unsigned integer, guaranteeing that at the time the value is incremented, no other thread is allowed to read or modify the value until the function returns.

Header File: platform_helper.h

WB_UINT32 WBInterlockedRead ( volatile WB_UINT32 pValue)

Interlocked 'atomic' read of an unsigned integer.

Parameters
pValue- a pointer to an 'unsigned int' to be read. Must be a valid pointer.
Returns
The value stored in 'pValue' after reading. The value will be read while write operations have been 'locked out'

This function performs an interlocked 'atomic' read of an unsigned integer, guaranteeing that at the time the value is read, no other thread is allowed to modify the value. Once read, the value can still change; however, the value as-read will be 'atomic' i.e. not a partially changed value.

Header File: platform_helper.h

int WBMutexCreate ( WB_MUTEX pMtx)

Create a lockable mutex.

Parameters
pMtxA pointer to the WB_MUTEX that will be created (could be a struct or just a pointer)
Returns
A zero value if successful; non-zero on error

Use this function to create a 'mutex' synchronization object that can be locked by only a single thread at a time

Header File: platform_helper.h

Definition at line 3633 of file platform_helper.c.

void WBMutexFree ( WB_MUTEX pMtx)

Free a lockable mutex.

Parameters
pMtxa pointer to the WB_MUTEX lockable mutex object

Use this function to free a WB_MUTEX that was previously allocated with WBMutexCreate()

Header File: platform_helper.h

Definition at line 3672 of file platform_helper.c.

int WBMutexLock ( WB_MUTEX pMtx,
int  nTimeout 
)

Wait for and lock a mutex, blocking until it is available.

Parameters
pMtxa pointer to the WB_MUTEX lockable mutex object
nTimeoutthe timeout period in microseconds, or a negative value to indicate 'INFINITE'
Returns
A zero if the lock succeeded, a value > 0 if the lock period timed out, or a negative value indicating error

This function attempts to lock the WB_MUTEX and returns a zero value if it succeeds, blocking for the period of time specified by 'nTimeout' (in microseconds). A negative 'nTimeout' causes an infinite waiting period. The function will return a positive value if the timeout period was exceeded, or a negative value on error.

Header File: platform_helper.h

Definition at line 3681 of file platform_helper.c.

int WBMutexUnlock ( WB_MUTEX pMtx)

Unlock a previously locked mutex.

Parameters
pMtxa pointer to the WB_MUTEX lockable mutex object
Returns
A zero if the unlock succeeded, non-zero on error

This function unlocks a previously locked mutex

Header File: platform_helper.h

Definition at line 3723 of file platform_helper.c.

WB_THREAD_KEY WBThreadAllocLocal ( void  )

Allocate 'thread local' storage.

Returns
The 'key' that identifies the thread local storage data slot

Allocate thread local storage, returning the identifier to that local storage slot

Header File: platform_helper.h

Definition at line 3358 of file platform_helper.c.

void WBThreadClose ( WB_THREAD  hThread)

Close the specified WB_THREAD identifier.

Parameters
hThreadthe WB_THREAD identifier

Call this function to close the WB_THREAD thread identifier specified by 'hThread'. Not closing the thread identifier can result in a 'zombie' thread that consumes resources. By closing the handle, you can allow a thread to run to its completion, and automatically delete the associated resources on exit. You should not call this function after a call to WBThreadWait()
NOTE: internally it calls either pthread_detach or CloseHandle (depending)

Header File: platform_helper.h

Definition at line 3572 of file platform_helper.c.

WB_THREAD WBThreadCreate ( void *(*)(void *)  function,
void *  pParam 
)

Create a new thread, returning its WB_THREAD identifier.

Parameters
functionA pointer to the callback function that runs the thread
pParamThe parameter to be passed to 'function' when it start
Returns
A WB_THREAD thread identifier, or INVALID_HANDLE_VALUE on error

Call this function to create a new thread using standard attributes.

Header File: platform_helper.h

Definition at line 3495 of file platform_helper.c.

void WBThreadExit ( void *  pRval)

Exit the current thread immediately, specifying return code.

Parameters
pRvalThe return code for the exiting thread

Call this function to exit the current thread immediately, specifying a return code
NOTE: when the thread proc returns, it implies a call to WBThreadExit() on completion, using the return value as the exit code.

Header File: platform_helper.h

Definition at line 3564 of file platform_helper.c.

void WBThreadFreeLocal ( WB_THREAD_KEY  keyVal)

Free 'thread local' storage allocated by WBThreadAllocLocal()

Returns
The 'key' that identifies the thread local storage data slot

Free an allocate thread local storage slot

Header File: platform_helper.h

Definition at line 3372 of file platform_helper.c.

WB_THREAD WBThreadGetCurrent ( void  )

Get 'current thread' identifier.

Returns
The WB_THREAD associated with the current thread

Returns a 'WB_THREAD' resource representing the current thread. This returned value should NOT be free'd using WBThreadClose(), nor waited on with WBThreadWait().

Header File: platform_helper.h

Definition at line 3396 of file platform_helper.c.

void* WBThreadGetLocal ( WB_THREAD_KEY  keyVal)

Get 'thread local' data identified by 'keyVal'.

Parameters
keyValthe 'WB_THREAD_KEY' identifier of the thread local data - see WBThreadAllocLocal()
Returns
The stored thread-specific data value, or NULL if not assigned

Get the data associated with a thread local storage slot

Header File: platform_helper.h

Definition at line 3380 of file platform_helper.c.

int WBThreadRunning ( WB_THREAD  hThread)

Determine whether a thread is running (can be suspended)

Parameters
hThreadthe WB_THREAD identifier
Returns
A value > 0 if the thread is running, < 0 on error, == 0 if the thread has ended and has a return code.

Use this function to determine whether a thread is still running. For a thread that has exited, it will return 0 indicating that there is an exit code available. If the thread has terminated (invalidating its WB_THREAD identifier) the function will return a value < 0. otherwise, The return value is > 0 indicating the thread is still active.
NOTE: an active thread that has been suspended will return a value > 0.

Header File: platform_helper.h

Definition at line 3531 of file platform_helper.c.

void WBThreadSetLocal ( WB_THREAD_KEY  keyVal,
void *  pValue 
)

Get 'thread local' data identified by 'keyVal'.

Parameters
keyValthe 'WB_THREAD_KEY' identifier of the thread local data - see WBThreadAllocLocal()
pValuethe value to assign for thread local data

Assign (set) the data associated with a thread local storage slot

Header File: platform_helper.h

Definition at line 3388 of file platform_helper.c.

void* WBThreadWait ( WB_THREAD  hThread)

Wait for a specified threat to exit.

Parameters
hThreadthe WB_THREAD identifier
Returns
The return value from the thread's thread proc or 'WBThreadExit()'

Call this function to wait for a thread to complete and/or obtain its exit code. This function will block until the thread has terminated or is canceled (pthreads only).

Header File: platform_helper.h

Definition at line 3515 of file platform_helper.c.