The thread API wrapper is an RDR-discoverable interface that provides access to a set of thread management calls. More...

Files
file	threadapi.h
	Header file defining the Threads interface.

file	ggsthreads.c
	Platform dependent parts of the threads API implementation for Windows.

file	threadcommon.c
	Platform independent parts of the threads API implementation.

file	threadcommon.h
	Platform independent parts of the threads API implementation.

Data Structures
struct	sw_pthread_api_20171022
	Thread API version sw_pthread_api_20171022 is a strict superset of the functionality in the sw_pthread_api_20111021 version of the thread interface. This is deliberate choice, and the layout of the 20111021 version is a prefix of the 20171022 version so a pointer to the latter may be used where a instance of the former is required. More...

struct	sw_pthread_api_20111021
	Thread API version sw_pthread_api_20111021 is a strict superset of the functionality in the sw_pthread_api_20071026 version of the thread interface. This is deliberate choice, and the layout of the 20071026 version is a prefix of the 20111021 version so a pointer to the latter may be used where a instance of the former is required. More...

struct	sw_pthread_api_20071026
	Thread API version `sw_pthread_api_20071026`. More...

Macros
#define	pthread_attr_init pthread_api->attr_init
	Initialize an attribute structure to pass non-default attributes to pthread_create(). More...

#define	pthread_attr_destroy pthread_api->attr_destroy
	Destroy an attribute structure previously initialized with pthread_attr_init(). More...

#define	pthread_attr_setdetachstate pthread_api->attr_setdetachstate
	Set the detach state of a thread attributes structure. More...

#define	pthread_create pthread_api->create
	Create a thread. More...

#define	pthread_join pthread_api->join
	Wait until a thread has been terminated. More...

#define	pthread_mutexattr_init pthread_api->mutexattr_init
	Initialize a mutex attribute structure to pass non-default attributes to pthread_mutex_init(). More...

#define	pthread_mutexattr_destroy pthread_api->mutexattr_destroy
	Destroy an attribute structure previously initialized with pthread_mutexattr_init(). More...

#define	pthread_mutexattr_getpshared pthread_api->mutexattr_getpshared
	Return the value of the process-shared attribute of the mutex attribute. More...

#define	pthread_mutexattr_setpshared pthread_api->mutexattr_setpshared
	Set a mutex attribute's process-shared attribute. More...

#define	pthread_mutexattr_settype pthread_api->mutexattr_settype
	Set a mutex attribute type. More...

#define	pthread_mutexattr_gettype pthread_api->mutexattr_gettype
	Return the value of the type attribute of the mutex attribute. More...

#define	pthread_mutex_init pthread_api->mutex_init
	Initialize a mutex object. More...

#define	pthread_mutex_destroy pthread_api->mutex_destroy
	Destroy a mutex object. More...

#define	pthread_mutex_lock pthread_api->mutex_lock
	Lock a mutex object. More...

#define	pthread_mutex_trylock pthread_api->mutex_trylock
	Try to lock a mutex object. More...

#define	pthread_mutex_unlock pthread_api->mutex_unlock
	Unlock a mutex object. More...

#define	pthread_cond_init pthread_api->cond_init
	Initialize a condition object. More...

#define	pthread_cond_destroy pthread_api->cond_destroy
	Destroy a condition object. More...

#define	pthread_cond_wait pthread_api->cond_wait
	Wait for a condition object to be signalled. More...

#define	pthread_cond_timedwait pthread_api->cond_timedwait
	Wait for a condition object to be signalled. More...

#define	pthread_cond_signal pthread_api->cond_signal
	Unblock at least one thread waiting on a condition object. More...

#define	pthread_cond_broadcast pthread_api->cond_broadcast
	Unblock all threads waiting on a condition object. More...

#define	pthread_key_create pthread_api->key_create
	Create a thread-local storage key. More...

#define	pthread_key_delete pthread_api->key_delete
	Delete a thread-local storage key previously created with pthread_key_create(). More...

#define	pthread_setspecific pthread_api->setspecific
	Set the value of a specified thread-local key for the current thread. More...

#define	pthread_getspecific pthread_api->getspecific
	Get the value of a specified thread-local key for the current thread. More...

#define	set_thread_name pthread_api->set_thread_name
	Set a thread name for debugging. More...

#define	get_time_from_now pthread_api->time_from_now
	Get the representation of time at given offset in the future from the current time, as a time since the epoch. All times are in microsecond units. More...

#define	hqtime_to_timespec pthread_api->hqtime_to_timespec
	Convert an HqU32x2 created by get_time_from_now() to a `struct timespec` suitable for pthread_cond_timedwait(). More...

Functions
HqBool	load_pthreads_dll (const char dll_name, char *error_string)
	Load the pthreads library. More...

HqBool	unload_pthreads_dll (void)
	Unload the pthreads library. More...

Detailed Description

The thread API wrapper is an RDR-discoverable interface that provides access to a set of thread management calls.

These calls are based on the Posix pthreads API, but not all calls in the pthreads API are exposed through this API. There are additional calls, e.g., to add debug names for threads, and to manage time manipulations suitable for passing to the pthreads API.

A thread API pointer must be discovered using RIP Data Resource (RDR) System using class RDR_CLASS_API and type RDR_API_PTHREADS and assigned to a suitably-named API pointer variable before the API macros are used. The application layer must set the thread API pointer before almost any SDK or core library call can be made.

Macro Definition Documentation

◆ get_time_from_now

#define get_time_from_now pthread_api->time_from_now

Get the representation of time at given offset in the future from the current time, as a time since the epoch. All times are in microsecond units.

Parameters

[in,out] time On invocation, *time contains an offset into the future. On completion, *time is updated to represent that future time relative to the epoch.

◆ hqtime_to_timespec

#define hqtime_to_timespec pthread_api->hqtime_to_timespec

Convert an HqU32x2 created by get_time_from_now() to a struct timespec suitable for pthread_cond_timedwait().

Parameters

[in]	hq_time	A time created by get_time_from_now().
[out]	spec_time	A time specification suitable for passing to pthread_cond_timedwait().

◆ pthread_attr_destroy

#define pthread_attr_destroy pthread_api->attr_destroy

Destroy an attribute structure previously initialized with pthread_attr_init().

Parameters

[out] attr Pointer to a thread attributes object to destroy.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_attr_destroy() specification for more detail.

◆ pthread_attr_init

#define pthread_attr_init pthread_api->attr_init

Initialize an attribute structure to pass non-default attributes to pthread_create().

Parameters

[out] attr Pointer to a thread attributes object to initialize.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_attr_init() specification for more detail.

◆ pthread_attr_setdetachstate

#define pthread_attr_setdetachstate pthread_api->attr_setdetachstate

Set the detach state of a thread attributes structure.

Parameters

[out]	attr	Pointer to a thread attributes object to destroy.
[in]	detachstate	Either `PTHREAD_CREATE_DETACHED` or `PTHREAD_CREATE_JOINABLE`.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_attr_setdetachstate() specification for more detail.

◆ pthread_cond_broadcast

#define pthread_cond_broadcast pthread_api->cond_broadcast

Unblock all threads waiting on a condition object.

Parameters

[in,out] cond A pointer to a condition object to signal.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_cond_broadcast() specification for more detail.

◆ pthread_cond_destroy

#define pthread_cond_destroy pthread_api->cond_destroy

Destroy a condition object.

Parameters

[in] cond A pointer to a condition object to destroy.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_cond_destroy() specification for more detail.

◆ pthread_cond_init

#define pthread_cond_init pthread_api->cond_init

Initialize a condition object.

Parameters

[out]	cond	A pointer to a condition object to initialize.
[in]	attr	A condition attributes structure, or `NULL` to use the default condition attributes.

Returns: 0 on success; otherwise an error number.

Note: The Harlequin core library and skin only use default condition attributes (i.e., setting attr to NULL). The ZMQ library used in the Scalable RIP may pass non-NULL values of attr on some platforms.

See the Posix pthread_cond_init() specification for more detail.

◆ pthread_cond_signal

#define pthread_cond_signal pthread_api->cond_signal

Unblock at least one thread waiting on a condition object.

Parameters

[in,out] cond A pointer to a condition object to signal.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_cond_signal() specification for more detail.

◆ pthread_cond_timedwait

#define pthread_cond_timedwait pthread_api->cond_timedwait

Wait for a condition object to be signalled.

Parameters

[in,out]	cond	A pointer to a condition object to wait on.
[in,out]	mutex	A mutex to release and re-lock around the condition wait.
[in]	timespec	A pointer to a time to stop waiting for the condition. A suitable time specification can be constructed by calling get_time_from_now() to get an end time relative to the current time, and then calling hqtime_to_timespec() to convert it to a `struct timespec` suitable for this parameter.

Returns: 0 on success; ETIMEDOUT if timed out; otherwise an error number.

See the Posix pthread_cond_timedwait() specification for more detail.

◆ pthread_cond_wait

#define pthread_cond_wait pthread_api->cond_wait

Wait for a condition object to be signalled.

Parameters

[in,out]	cond	A pointer to a condition object to wait on.
[in,out]	mutex	A mutex to release and re-lock around the condition wait.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_cond_wait() specification for more detail.

◆ pthread_create

#define pthread_create pthread_api->create

Create a thread.

Parameters

[out]	thread	Location to store the new thread ID if successful.
[in]	attr	A thread attributes structure, or `NULL` to use the default thread attributes.
[in]	start	A function to run on the new thread, taking arg as its sole argument.
[in]	arg	A pointer to pass to start when executed by the new thread.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_create() specification for more detail.

◆ pthread_getspecific

#define pthread_getspecific pthread_api->getspecific

Get the value of a specified thread-local key for the current thread.

Parameters

[in] key A thread-local key previously created with pthread_key_create().

Returns: The value previously set using pthread_setspecific() for this thread, or NULL if it has not been set for this thread.

See the Posix pthread_key_getspecific() specification for more detail.

◆ pthread_join

#define pthread_join pthread_api->join

Wait until a thread has been terminated.

Parameters

[in]	thread	Location to store the new thread ID if successful.
[out]	presult	An optional pointer to receive the return value of the thread start function.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_join() specification for more detail.

◆ pthread_key_create

#define pthread_key_create pthread_api->key_create

Create a thread-local storage key.

Parameters

[out]	key	Location to store the thread-local key if successful.
[in]	destructor	The destructor parameter should be `NULL`, it is not used by the Harlequin core library or SDK, and is not supported on all platform implementations.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_key_create() specification for more detail.

◆ pthread_key_delete

#define pthread_key_delete pthread_api->key_delete

Delete a thread-local storage key previously created with pthread_key_create().

Parameters

[in] key The thread-local key to delete.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_key_delete() specification for more detail.

◆ pthread_mutex_destroy

#define pthread_mutex_destroy pthread_api->mutex_destroy

Destroy a mutex object.

Parameters

[out] mutex A pointer to a mutex object to destroy.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_mutex_destroy() specification for more detail.

◆ pthread_mutex_init

#define pthread_mutex_init pthread_api->mutex_init

Initialize a mutex object.

Parameters

[out]	mutex	A pointer to a mutex object to initialize.
[in]	attr	A mutex attributes structure, or `NULL` to use the default mutex attributes.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_mutex_init() specification for more detail.

◆ pthread_mutex_lock

#define pthread_mutex_lock pthread_api->mutex_lock

Lock a mutex object.

Parameters

[in,out] mutex A pointer to a mutex object to lock.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_mutex_lock() specification for more detail.

◆ pthread_mutex_trylock

#define pthread_mutex_trylock pthread_api->mutex_trylock

Try to lock a mutex object.

Parameters

[in,out] mutex A pointer to a mutex object to lock.

Returns: 0 on success; EBUSY if the mutex is already locked; otherwise an error number.

See the Posix pthread_mutex_trylock() specification for more detail.

◆ pthread_mutex_unlock

#define pthread_mutex_unlock pthread_api->mutex_unlock

Unlock a mutex object.

Parameters

[in,out] mutex A pointer to a mutex object to unlock.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_mutex_unlock() specification for more detail.

◆ pthread_mutexattr_destroy

#define pthread_mutexattr_destroy pthread_api->mutexattr_destroy

Destroy an attribute structure previously initialized with pthread_mutexattr_init().

Parameters

[out] attr Pointer to a mutex thread attributes object to destroy.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_mutexattr_destroy() specification for more detail.

◆ pthread_mutexattr_getpshared

#define pthread_mutexattr_getpshared pthread_api->mutexattr_getpshared

Return the value of the process-shared attribute of the mutex attribute.

Parameters

[in]	attr	A mutex attribute object.
[out]	pshared	A location to store the process-shared attribute.

Returns: 0 on success; otherwise an error number.

Note: Neither the Harlequin core library nor skin use this call. This pointer may be set to NULL in the API structure.

See the Posix pthread_mutexattr_getpshared() specification for more detail.

◆ pthread_mutexattr_gettype

#define pthread_mutexattr_gettype pthread_api->mutexattr_gettype

Return the value of the type attribute of the mutex attribute.

Parameters

[in]	attr	A mutex attribute object.
[out]	ptype	A location to store the type attribute.

Returns: 0 on success; otherwise an error number.

Note: Neither the Harlequin core library nor skin use this call. This pointer may be set to NULL in the API structure.

See the Posix pthread_mutexattr_gettype() specification for more detail.

◆ pthread_mutexattr_init

#define pthread_mutexattr_init pthread_api->mutexattr_init

Initialize a mutex attribute structure to pass non-default attributes to pthread_mutex_init().

Parameters

[out] attr Pointer to a mutex attributes object to initialize.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_mutexattr_init() specification for more detail.

◆ pthread_mutexattr_setpshared

#define pthread_mutexattr_setpshared pthread_api->mutexattr_setpshared

Set a mutex attribute's process-shared attribute.

Parameters

[out]	attr	A mutex attribute object.
[in]	shared	Either `PTHREAD_PROCESS_PRIVATE` or `PTHREAD_PROCESS_SHARED`.

Returns: 0 on success; otherwise an error number.

Note: Neither the Harlequin core library nor skin use this call. This pointer may be set to NULL in the API structure.

See the Posix pthread_mutexattr_setpshared() specification for more detail.

◆ pthread_mutexattr_settype

#define pthread_mutexattr_settype pthread_api->mutexattr_settype

Set a mutex attribute type.

Parameters

[out]	attr	A mutex attribute object.
[in]	type	One of `PTHREAD_MUTEX_NORMAL`, `PTHREAD_MUTEX_ERRORCHECK`, `PTHREAD_MUTEX_RECURSIVE`, or `PTHREAD_MUTEX_DEFAULT`.

Returns: 0 on success; otherwise an error number.

Note: The Harlequin core library and skin only set type to PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE. Mutexes are also created using default attributes by passing a NULL attributes pointer to pthread_mutex_init().

See the Posix pthread_mutexattr_settype() specification for more detail.

◆ pthread_setspecific

#define pthread_setspecific pthread_api->setspecific

Set the value of a specified thread-local key for the current thread.

Parameters

[in]	key	A thread-local key previously created with pthread_key_create().
[in]	value	The value to set this thread-local key to.

Returns: 0 on success; otherwise an error number.

See the Posix pthread_key_setspecific() specification for more detail.

◆ set_thread_name

#define set_thread_name pthread_api->set_thread_name

Set a thread name for debugging.

Parameters

[in] name The name to use for the current thread. This may be changed during execution to reflect current usage of the thread.

Function Documentation

◆ load_pthreads_dll()

HqBool load_pthreads_dll	(	const char *	dll_name,
		char **	error_string
	)

Load the pthreads library.

Parameters

[in]	dll_name	The leafname of the dynamically load library. The library is searched for using the library search path. This leafname be NULL, in which case the default library leafname will be used.
[out]	error_string	A pointer to receive an error string.

Return values

TRUE	if the pthreads library was loaded.
FALSE	if the pthreads library was not loaded. If the library was not loaded, then an error string is set through the error_string pointer.

This call is required on Windows. It is a stub on other platforms.

◆ unload_pthreads_dll()

HqBool unload_pthreads_dll ( void )

Unload the pthreads library.

Return values

TRUE	if the pthreads library was unloaded cleanly.
FALSE	if the pthreads library was not unloaded cleanly.

This call is required on Windows. It is a stub on other platforms.

Files

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ get_time_from_now

◆ hqtime_to_timespec

◆ pthread_attr_destroy

◆ pthread_attr_init

◆ pthread_attr_setdetachstate

◆ pthread_cond_broadcast

◆ pthread_cond_destroy

◆ pthread_cond_init

◆ pthread_cond_signal

◆ pthread_cond_timedwait

◆ pthread_cond_wait

◆ pthread_create

◆ pthread_getspecific

◆ pthread_join

◆ pthread_key_create

◆ pthread_key_delete

◆ pthread_mutex_destroy

◆ pthread_mutex_init

◆ pthread_mutex_lock

◆ pthread_mutex_trylock

◆ pthread_mutex_unlock

◆ pthread_mutexattr_destroy

◆ pthread_mutexattr_getpshared

◆ pthread_mutexattr_gettype

◆ pthread_mutexattr_init

◆ pthread_mutexattr_setpshared

◆ pthread_mutexattr_settype

◆ pthread_setspecific

◆ set_thread_name

Function Documentation

◆ load_pthreads_dll()

◆ unload_pthreads_dll()