"Dinkum/threads/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.
cnd_broadcast
int cnd_broadcast(cnd_t *cond);
Returns: the usual return value.
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 mutexmtx_timed
-- for a
non-recursive mutex that supports
timeoutmtx_try
-- for a
non-recursive mutex that supports
test and returnmtx_plain | mtx_recursive
--
for a simple
recursive mutexmtx_timed | mtx_recursive
-- for a
recursive mutex that supports
timeoutmtx_try | mtx_recursive
-- for a
recursive mutex that supports
test and returnIf 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.
Copyright © 1992-2013 by Dinkumware, Ltd. Portions derived from work Copyright © 2001 by William E. Kempf. All rights reserved.