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

◆ WBCondCreate()

int WBCondCreate ( WB_COND * pCond )

Create a signallable condition.

Parameters

pCond A 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 4869 of file platform_helper.c.

◆ WBCondFree()

void WBCondFree ( WB_COND * pCond )

Free a signallable condition.

Parameters

pCond a 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 4925 of file platform_helper.c.

◆ WBCondSignal()

int WBCondSignal ( WB_COND * pCond )

Signal a condition (event)

Parameters

pCond a 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 5007 of file platform_helper.c.

◆ WBCondWait()

int WBCondWait	(	WB_COND *	pCond,
		int	nTimeout
	)

Wait for a signal on a condition (event)

Parameters

pCond	a poiner to the WB_COND condition object
nTimeout	the 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 5023 of file platform_helper.c.

◆ WBCondWaitMutex()

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

Wait for a signal on a condition (event)

Parameters

pCond	a pointer to the WB_COND condition object
pMtx	a pointer to a locked WB_MUTEX object
nTimeout	the 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 5096 of file platform_helper.c.

◆ WBInterlockedDecrement()

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

Definition at line 5163 of file platform_helper.c.

◆ WBInterlockedExchange()

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

Definition at line 5199 of file platform_helper.c.

◆ WBInterlockedIncrement()

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

Definition at line 5181 of file platform_helper.c.

◆ WBInterlockedRead()

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

Definition at line 5216 of file platform_helper.c.

◆ WBMutexCreate()

int WBMutexCreate ( WB_MUTEX * pMtx )

Create a lockable mutex.

Parameters

pMtx	A 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 4908 of file platform_helper.c.

◆ WBMutexFree()

void WBMutexFree ( WB_MUTEX * pMtx )

Free a lockable mutex.

Parameters

pMtx	a 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 4947 of file platform_helper.c.

◆ WBMutexLock()

int WBMutexLock	(	WB_MUTEX *	pMtx,
		int	nTimeout
	)

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

Parameters

pMtx	a pointer to the WB_MUTEX lockable mutex object
nTimeout	the 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 4956 of file platform_helper.c.

◆ WBMutexUnlock()

int WBMutexUnlock ( WB_MUTEX * pMtx )

Unlock a previously locked mutex.

Parameters

pMtx	a 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 4998 of file platform_helper.c.

◆ WBThreadAllocLocal()

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 4633 of file platform_helper.c.

◆ WBThreadClose()

void WBThreadClose ( WB_THREAD hThread )

Close the specified WB_THREAD identifier.

Parameters

hThread the 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 4847 of file platform_helper.c.

◆ WBThreadCreate()

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

Create a new thread, returning its WB_THREAD identifier.

Parameters

function	A pointer to the callback function that runs the thread
pParam	The 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 4770 of file platform_helper.c.

◆ WBThreadExit()

void WBThreadExit ( void * pRval )

Exit the current thread immediately, specifying return code.

Parameters

pRval The 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 4839 of file platform_helper.c.

◆ WBThreadFreeLocal()

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 4647 of file platform_helper.c.

◆ WBThreadGetCurrent()

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 4671 of file platform_helper.c.

◆ WBThreadGetLocal()

void* WBThreadGetLocal ( WB_THREAD_KEY keyVal )

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

Parameters

keyVal the '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 4655 of file platform_helper.c.

◆ WBThreadRunning()

int WBThreadRunning ( WB_THREAD hThread )

Determine whether a thread is running (can be suspended)

Parameters

hThread the 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 4806 of file platform_helper.c.

◆ WBThreadSetLocal()

void WBThreadSetLocal	(	WB_THREAD_KEY	keyVal,
		void *	pValue
	)

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

Parameters

keyVal	the 'WB_THREAD_KEY' identifier of the thread local data - see WBThreadAllocLocal()
pValue	the 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 4663 of file platform_helper.c.

◆ WBThreadWait()

void* WBThreadWait ( WB_THREAD hThread )

Wait for a specified threat to exit.

Parameters

hThread the 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 4790 of file platform_helper.c.

Functions

Detailed Description

Function Documentation

◆ WBCondCreate()

◆ WBCondFree()

◆ WBCondSignal()

◆ WBCondWait()

◆ WBCondWaitMutex()

◆ WBInterlockedDecrement()

◆ WBInterlockedExchange()

◆ WBInterlockedIncrement()

◆ WBInterlockedRead()

◆ WBMutexCreate()

◆ WBMutexFree()

◆ WBMutexLock()

◆ WBMutexUnlock()

◆ WBThreadAllocLocal()

◆ WBThreadClose()

◆ WBThreadCreate()

◆ WBThreadExit()

◆ WBThreadFreeLocal()

◆ WBThreadGetCurrent()

◆ WBThreadGetLocal()

◆ WBThreadRunning()

◆ WBThreadSetLocal()

◆ WBThreadWait()