threads.h"`

call_once · cnd_broadcast · cnd_broadcast_at_thread_exit · cnd_destroy · cnd_init · cnd_signal · cnd_t · cnd_timedwait · cnd_wait · mtx_destroy · mtx_init · mtx_lock · mtx_plain · mtx_recursive · mtx_t · mtx_timed · mtx_timedlock · mtx_try · mtx_trylock · mtx_unlock · once_flag · ONCE_FLAG_INIT · thrd_abort · thrd_busy · thrd_create · thrd_current · thrd_detach · thrd_equal · thrd_error · thrd_exit · thrd_join · thrd_nomem · thrd_sleep · thrd_start_t · thrd_success · thrd_t · thrd_timedout · thrd_yield · tss_create · TSS_DTOR_ITERATIONS · tss_delete · tss_dtor_t · tss_get · tss_set · tss_t

Include the header "Dinkum/threads/threads.h" so that you can perform thread-related operations.

    /* RETURN VALUES */
enum {
    thrd_success = .....,
    thrd_nomem = .....,
    thrd_timedout = .....,
    thrd_busy = .....,
    thrd_error = .....
    };

    /* THREADS */
typedef o-type thrd_t;
typedef int (*thrd_start_t)(void*);

int thrd_create(thrd_t *, thrd_start_t, void*);
int thrd_detach(thrd_t);
void thrd_exit(int);
int thrd_join(thrd_t, int*);
void thrd_sleep(const xtime*);
void thrd_yield(void);

int thrd_equal(thrd_t, thrd_t);
thrd_t thrd_current(void);

    /* MUTEXES */
typedef o-type mtx_t;
enum {
    mtx_plain = .....,
    mtx_try = .....,
    mtx_timed = .....,
    mtx_recursive = .....
    };

int mtx_init(mtx_t*, int);
void mtx_destroy(mtx_t*);
int mtx_lock(mtx_t*);
int mtx_trylock(mtx_t*);
int mtx_timedlock(mtx_t*, const xtime*);
int mtx_unlock(mtx_t*);

    /* CONDITION VARIABLES */
typedef o_type cnd_t ;

int cnd_init(cnd_t*);
void cnd_destroy(cnd_t*);
int cnd_wait(cnd_t*, mtx_t*);
int cnd_timedwait(cnd_t*, mtx_t*, const xtime*);
int cnd_signal(cnd_t*);
int cnd_broadcast(cnd_t*);
int cnd_broadcast_at_thread_exit(cnd_t*, mtx_t*);

    /* THREAD-SPECIFIC STORAGE */
typedef i-type tss_t;
typedef void (*tss_dtor_t)(void*);

int tss_create(tss_t*, tss_dtor_t);
int tss_delete(tss_t);
int tss_set(tss_t, void*);
void *tss_get(tss_t);
#define TSS_DTOR_ITERATIONS <integer constant expression>

    /* ONCE FUNCTIONS */
typedef o-type once_flag;

#define ONCE_FLAG_INIT <object initializer>
void call_once(once_flag*, void (*)(void));

    /* UTILITY FUNCTIONS */
void thrd_abort(const char *);

`call_once`

void call_once(once_flag *flag, void (*func)(void));

The function uses *flag to ensure that func is called exactly once.

The function unblocks all of the threads that are blocked on the condition variable *cond at the time of the call. If no threads are blocked on the condition variable at the time of the call the function does nothing.

`cnd_broadcast_at_thread_exit`

int cnd_broadcast_at_thread_exit(cnd_t *cond, mtx_t *mtx);

Requires: the mutex *mtx must be locked by the calling thread and all threads blocked on cond must have been locked using *mtx.

Returns: the usual return value.

The function registers the condition variable cond so that all threads that are blocked on cond will be unblocked by a call to cnd_broadcast(cond) when the current thread terminates, after all of the destructors for the current thread's thread-specific storage have been run. The function does not unlock *mtx, but *mtx will be unlocked immediately after the subsequent call to cnd_broadcast(cond).

`cnd_destroy`

void cnd_destroy(cnd_t *cond);

Precondition: no threads are blocked waiting for *cond.

The function releases any resources used by the condition variable *cond.

`cnd_init`

int cnd_init(cnd_t *cond);

Returns: the usual return value.

The function creates a condition variable. If it succeeds it sets *cond to a value that uniquely identifies the newly created condition variable. A thread that calls cnd_wait on a newly created condition variable will block.

`cnd_signal`

int cnd_signal(cnd_t *cond);

Returns: the usual return value.

The function unblocks one of the threads that is blocked on the condition variable *cond at the time of the call. If no threads are blocked on the condition variable at the time of the call the function does nothing.

`cnd_t`

typedef o-type cnd_t;

The type is an object type o-type that holds an identifier for a condition variable.

`cnd_timedwait`

int cnd_timedwait(cnd_t *cond, mtx_t *mtx, const xtime *xt);

Requires: the mutex *mtx must be locked by the calling thread.

Returns: the usual return value.

The function atomically unlocks the mutex mtx and blocks until the condition variable *cond is signaled by a call to cnd_signal or to cnd_broadcast, or until after the time specified by the xtime object *xt. When the calling thread becomes unblocked it locks *mtx before it returns.

`cnd_wait`

int cnd_wait(cnd_t *cond, mtx_t *mtx);

Requires: the mutex *mtx must be locked by the calling thread.

Returns: the usual return value.

The function atomically unlocks the mutex and blocks until the condition variable *cond is signaled by a call to cnd_signal or to cnd_broadcast. When the calling thread becomes unblocked it locks *mtx before it returns.

`mtx_destroy`

void mtx_destroy(mtx_t *mtx);

Precondition: no threads are blocked waiting for *mtx.

The function releases any resources used by the mutex *mtx.

`mtx_init`

int mtx_init(mtx_t *mtx, int type);

Returns: the usual return value.

The function creates a mutex object with properties indicated by type, which must have one of the six values

mtx_plain -- for a simple non-recursive mutex
mtx_timed -- for a non-recursive mutex that supports timeout
mtx_try -- for a non-recursive mutex that supports test and return
mtx_plain | mtx_recursive -- for a simple recursive mutex
mtx_timed | mtx_recursive -- for a recursive mutex that supports timeout
mtx_try | mtx_recursive -- for a recursive mutex that supports test and return

If it succeeds it sets *mtx to a value that uniquely identifies the newly created mutex. The mutex is not locked.

`mtx_lock`

int mtx_lock(mtx_t *mtx);

Precondition: if the mutex is non-recursive it must not be locked by the calling thread.

Returns: the usual return value.

The function blocks until it locks the mutex *mtx.

`mtx_plain`

enum { mtx_plain = ..... };

The compile-time constant is passed to mtx_init to create a mutex object that supports neither timeout nor test and return.

`mtx_recursive`

enum { mtx_recursive = ..... };

The compile-time constant is passed to mtx_init to create a mutex object that supports recursive locking.

`mtx_t`

typedef o-type mtx_t;

The type is an object type o-type that holds an identifier for a mutex.

`mtx_timed`

enum { mtx_timed = ..... };

The compile-time constant is passed to mtx_init to create a mutex object that supports timeout.

`mtx_timedlock`

int mtx_timedlock(mtx_t *mtx, const xtime *xt);

Precondition: the mutex *mtx must be of type mtx_timed or of type mtx_timed | mtx_recursive.

Returns: the usual return value.

The function blocks until it locks the mutex *mtx or until the time specified by the xtime object *xt.

`mtx_try`

enum { mtx_try = ..... };

The compile-time constant is passed to mtx_init to create a mutex object that supports test and return.

`mtx_trylock`

int mtx_trylock(mtx_t *mtx);

Precondition: the mutex *mtx must be of type mtx_try, of type mtx_try | mtx_recursive, of type mtx_timed, or of type mtx_timed | mtx_recursive.

Returns: the usual return value.

The function attempts to lock the mutex *mtx. If the mutex is already locked the function returns without blocking.

`mtx_unlock`

int mtx_unlock(mtx_t *mtx);

Precondition: the mutex *mtx must be locked by the calling thread.

Returns: the usual return value.

The function unlocks the mutex *mtx.

`once_flag`

typedef o-type once_flag;

The type is an object type o-type that holds a flag for use by call_once.

`ONCE_FLAG_INIT`

#define ONCE_FLAG_INIT <object initializer>

The macro yields a value that can be used to initialize an object of type once_flag.

`thrd_abort`

void thrd_abort(const char *msg);

The function writes msg to standard error then calls abort.

`thrd_busy`

enum { thrd_busy = ..... };

The compile-time constant is returned by a function to indicate that the requested operation failed because a resource requested by a test and return function is already in use.

`thrd_create`

int thrd_create(thrd_t *thr, thrd_start_t func, void *arg);

Returns: the usual return value.

The function creates a new thread executing func(arg). If it succeeds it sets *thr to a value that uniquely identifies the newly created thread. The function does not return until the new thread has begun execution.

`thrd_current`

thrd_t thrd_current(void);

The function returns a value that uniquely identifies the thread that called it.

`thrd_detach`

int thrd_detach(thrd_t thr);

Requires: the application must not have previously called thrd_detach or thrd_join for the thread identified by thr.

Returns: the usual return value.

The function tells the operating system to dispose of any resources allocated to the thread identified by thr when that thread terminates.

`thrd_equal`

int thrd_equal(thrd_t thr0, thrd_t thr1);

The function returns zero if thr0 and thr1 refer to different threads. Otherwise it returns a non-zero value.

`thrd_error`

enum { thrd_error = ..... };

The compile-time constant is returned by a function to indicate that the requested operation failed.

`thrd_exit`

void thrd_exit(int res);

The function terminates execution of the calling thread and sets its result code to res.

`thrd_join`

int thrd_join(thrd_t thr, int *res);

Requires: the application must not have previously called thrd_join or thrd_detach for the thread identified by thr.

Returns: the usual return value.

The function tells the operating system to dispose of any resources allocated to the thread identified by thr when that thread terminates and blocks until that thread has terminated. If res is not a null pointer it stores the thread's result code in *res.

`thrd_nomem`

enum { thrd_nomem = ..... };

The compile-time constant is returned by a function to indicate that the requested operation failed because it was unable to allocate memory.

`thrd_sleep`

void thrd_sleep(const xtime *xt);

The function suspends execution of the calling thread until after the time specified by the xtime object *xt.

`thrd_start_t`

typedef int (*thrd_start_t)(void*);

The type is the function type that is passed to thrd_create to create a new thread.

`thrd_success`

enum { thrd_success = ..... };

The compile-time constant is returned by a function to indicate that the requested operation succeeded.

`thrd_t`

typedef o-type thrd_t;

The type is an object type o-type that holds an identifier for a thread.

`thrd_timedout`

enum { thrd_timedout = ..... };

The compile-time constant is returned by a timed wait function to indicate that the time specified in the call was reached without acquiring the requested resource.

`thrd_yield`

void thrd_yield(void);

The function permits other threads to run even if the current thread would ordinarily continue to run.

`tss_create`

int tss_create(tss_t *key, tss_dtor_t dtor);

Returns: the usual return value.

The function creates a thread-specific storage pointer with destructor dtor, which may be null. If it succeeds it sets *key to a value that uniquely identifies the newly created pointer.

`TSS_DTOR_ITERATIONS`

#define TSS_DTOR_ITERATIONS <integer constant expression>

The macro yields the maximum number of times that destructors will be called when a thread terminates.

`tss_dtor_t`

typedef void (*tss_dtor_t)(void*);

The type is the function type for a destructor for a thread-specific storage pointer.

`tss_delete`

void tss_delete(tss_t key);

The function releases any resources used by the thread-specific storage pointer key.

`tss_get`

void *tss_get(tss_t key);

The function returns the value for the current thread held in the thread-specific storage pointer identified by key.

`tss_set`

int tss_set(tss_t key, void *val);

Returns: the usual return value.

The function sets the value for the current thread held in the thread-specific storage pointer identified by key to val.

`tss_t`

typedef o-type tss_t;

The type is an object type o-type that holds an identifier for a thread-specific storage pointer.

See also the Table of Contents and the Index.