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

#include "threadapi.h"

Data Fields
int(*	attr_init )(pthread_attr_t *)
	Initialize an attribute structure to pass non-default attributes to pthread_create(). More...

int(*	attr_destroy )(pthread_attr_t *)
	Destroy an attribute structure previously initialized with pthread_attr_init(). More...

int(*	attr_setdetachstate )(pthread_attr_t *, int)
	Set the detach state of a thread attributes structure. More...

int(*	create )(pthread_t , const pthread_attr_t , void (start)(void ), void )
	Create a thread. More...

int(*	join )(pthread_t, void **)
	Wait until a thread has been terminated. More...

int(*	mutexattr_init )(pthread_mutexattr_t *)
	Initialize a mutex attribute structure to pass non-default attributes to pthread_mutex_init(). More...

int(*	mutexattr_destroy )(pthread_mutexattr_t *)
	Destroy an attribute structure previously initialized with pthread_mutexattr_init(). More...

int(*	mutexattr_getpshared )(const pthread_mutexattr_t , int )
	Return the value of the process-shared attribute of the mutex attribute. More...

int(*	mutexattr_setpshared )(pthread_mutexattr_t *, int)
	Set a mutex attribute's process-shared attribute. More...

int(*	mutexattr_settype )(pthread_mutexattr_t *, int)
	Set a mutex attribute type. More...

int(*	mutexattr_gettype )(const pthread_mutexattr_t , int )
	Return the value of the type attribute of the mutex attribute. More...

int(*	mutex_init )(pthread_mutex_t , const pthread_mutexattr_t )
	Initialize a mutex object. More...

int(*	mutex_destroy )(pthread_mutex_t *)
	Destroy a mutex object. More...

int(*	mutex_lock )(pthread_mutex_t *)
	Try to lock a mutex object. More...

int(*	mutex_trylock )(pthread_mutex_t *)
	Try to lock a mutex object. More...

int(*	mutex_unlock )(pthread_mutex_t *)
	Unlock a mutex object. More...

int(*	cond_init )(pthread_cond_t , const pthread_condattr_t )
	Initialize a condition object. More...

int(*	cond_destroy )(pthread_cond_t *)
	Destroy a condition object. More...

int(*	cond_wait )(pthread_cond_t , pthread_mutex_t )
	Wait for a condition object to be signalled. More...

int(*	cond_timedwait )(pthread_cond_t , pthread_mutex_t , const struct timespec *)
	Wait for a condition object to be signalled. More...

int(*	cond_signal )(pthread_cond_t *)
	Unblock at least one thread waiting on a condition object. More...

int(*	cond_broadcast )(pthread_cond_t *)
	Unblock all threads waiting on a condition object. More...

void(*	set_thread_name )(const char *name)
	Set a thread name for debugging. More...

HqBool	valid
	Is this API structure valid?

void(*	time_from_now )(struct HqU32x2 *time)
	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...

int(*	key_create )(pthread_key_t , void(destructor)(void *))
	Create a thread-local storage key. More...

int(*	key_delete )(pthread_key_t)
	Delete a thread-local storage key previously created with pthread_key_create(). More...

int(*	setspecific )(pthread_key_t, const void *)
	Set the value of a specified thread-local key for the current thread. More...

void (	getspecific )(pthread_key_t)
	Get the value of a specified thread-local key for the current thread. More...

void(*	hqtime_to_timespec )(const struct HqU32x2 hq_time, struct timespec spec_time)
	Convert an HqU32x2 created by get_time_from_now() to a `struct timespec` suitable for pthread_cond_timedwait(). More...

Detailed Description

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.

Field Documentation

◆ attr_destroy

int( * sw_pthread_api_20171022::attr_destroy) (pthread_attr_t *)

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.

◆ attr_init

int( * sw_pthread_api_20171022::attr_init) (pthread_attr_t *)

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.

◆ attr_setdetachstate

int( * sw_pthread_api_20171022::attr_setdetachstate) (pthread_attr_t *, int)

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.

◆ cond_broadcast

int( * sw_pthread_api_20171022::cond_broadcast) (pthread_cond_t *)

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.

◆ cond_destroy

int( * sw_pthread_api_20171022::cond_destroy) (pthread_cond_t *)

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.

◆ cond_init

int( * sw_pthread_api_20171022::cond_init) (pthread_cond_t *, const pthread_condattr_t *)

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.

◆ cond_signal

int( * sw_pthread_api_20171022::cond_signal) (pthread_cond_t *)

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.

◆ cond_timedwait

int( * sw_pthread_api_20171022::cond_timedwait) (pthread_cond_t *, pthread_mutex_t *, const struct timespec *)

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.

◆ cond_wait

int( * sw_pthread_api_20171022::cond_wait) (pthread_cond_t *, pthread_mutex_t *)

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.

◆ create

int( * sw_pthread_api_20171022::create) (pthread_t *, const pthread_attr_t *, void *(*start)(void *), void *)

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.

◆ getspecific

void*( * sw_pthread_api_20171022::getspecific) (pthread_key_t)

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.

◆ hqtime_to_timespec

void( * sw_pthread_api_20171022::hqtime_to_timespec) (const struct HqU32x2 *hq_time, struct timespec *spec_time)

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

◆ join

int( * sw_pthread_api_20171022::join) (pthread_t, void **)

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.

◆ key_create

int( * sw_pthread_api_20171022::key_create) (pthread_key_t *, void(*destructor)(void *))

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.

◆ key_delete

int( * sw_pthread_api_20171022::key_delete) (pthread_key_t)

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.

◆ mutex_destroy

int( * sw_pthread_api_20171022::mutex_destroy) (pthread_mutex_t *)

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.

◆ mutex_init

int( * sw_pthread_api_20171022::mutex_init) (pthread_mutex_t *, const pthread_mutexattr_t *)

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.

◆ mutex_lock

int( * sw_pthread_api_20171022::mutex_lock) (pthread_mutex_t *)

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.

◆ mutex_trylock

int( * sw_pthread_api_20171022::mutex_trylock) (pthread_mutex_t *)

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.

◆ mutex_unlock

int( * sw_pthread_api_20171022::mutex_unlock) (pthread_mutex_t *)

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.

◆ mutexattr_destroy

int( * sw_pthread_api_20171022::mutexattr_destroy) (pthread_mutexattr_t *)

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.

◆ mutexattr_getpshared

int( * sw_pthread_api_20171022::mutexattr_getpshared) (const pthread_mutexattr_t *, int *)

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.

◆ mutexattr_gettype

int( * sw_pthread_api_20171022::mutexattr_gettype) (const pthread_mutexattr_t *, int *)

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.

◆ mutexattr_init

int( * sw_pthread_api_20171022::mutexattr_init) (pthread_mutexattr_t *)

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.

◆ mutexattr_setpshared

int( * sw_pthread_api_20171022::mutexattr_setpshared) (pthread_mutexattr_t *, int)

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.

◆ mutexattr_settype

int( * sw_pthread_api_20171022::mutexattr_settype) (pthread_mutexattr_t *, int)

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.

◆ set_thread_name

void( * sw_pthread_api_20171022::set_thread_name) (const char *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.

◆ setspecific

int( * sw_pthread_api_20171022::setspecific) (pthread_key_t, const void *)

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.

◆ time_from_now

void( * sw_pthread_api_20171022::time_from_now) (struct HqU32x2 *time)

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.

The documentation for this struct was generated from the following file:

lib/interface/threadapi.h

Data Fields

Detailed Description

Field Documentation

◆ attr_destroy

◆ attr_init

◆ attr_setdetachstate

◆ cond_broadcast

◆ cond_destroy

◆ cond_init

◆ cond_signal

◆ cond_timedwait

◆ cond_wait

◆ create

◆ getspecific

◆ hqtime_to_timespec

◆ join

◆ key_create

◆ key_delete

◆ mutex_destroy

◆ mutex_init

◆ mutex_lock

◆ mutex_trylock

◆ mutex_unlock

◆ mutexattr_destroy

◆ mutexattr_getpshared

◆ mutexattr_gettype

◆ mutexattr_init

◆ mutexattr_setpshared

◆ mutexattr_settype

◆ set_thread_name

◆ setspecific

◆ time_from_now