rthreads.h File Reference

Threads, mutexes (plain, recursive, read/write), condition variables, thread-specific storage and one-shot initialisation. More...

#include <rlib/rtypes.h>
#include <rlib/concurrency/ratomic.h>
#include <rlib/data/rbitset.h>
#include <rlib/rref.h>

Go to the source code of this file.

Data Structures
struct	ROnce
	One-shot initialisation guard. More...
struct	RTss
	Thread-specific storage slot. More...

Macros
#define	R_ONCE_INIT   { R_ONCE_STATE_INIT, NULL }
	Static initialiser for an ROnce in INIT state.
#define	R_TSS_INIT(notify)   { (RDestroyNotify)(notify), { NULL } }
	Static initialiser for an RTss with destroy callback notify; pass NULL to disable cleanup on r_tss_set or thread exit.

Typedefs
typedef rpointer	RMutex
	Opaque mutex handle; initialise with r_mutex_init.
typedef rpointer	RRMutex
	Opaque recursive-mutex handle; initialise with r_rmutex_init.
typedef rpointer	RRWMutex
	Opaque read/write-mutex handle; initialise with r_rwmutex_init.
typedef rpointer	RCond
	Opaque condition-variable handle; initialise with r_cond_init.
typedef rpointer(*	RThreadFunc) (rpointer data)
	Thread entry-point signature.
typedef struct RThread	RThread
	Opaque, refcounted thread handle returned by r_thread_new_full.

Enumerations
enum	ROnceState { R_ONCE_STATE_INIT , R_ONCE_STATE_RUNNING , R_ONCE_STATE_DONE }
	Lifecycle states of an ROnce. More...

Functions
rpointer	r_call_once (ROnce *once, RThreadFunc f, rpointer a)
	Run f exactly once across all threads, return its result.
Thread-specific storage (TSS)
rpointer	r_tss_get (RTss *tss)
	Retrieve this thread's TSS value, or NULL if unset.
void	r_tss_set (RTss *tss, rpointer data)
	Set this thread's TSS value, freeing the previous one via the notify callback if any.
Non-recursive mutex
void	r_mutex_init (RMutex *mutex)
	Initialise a fresh RMutex.
void	r_mutex_clear (RMutex *mutex)
	Release OS resources held by mutex; must be unlocked first.
void	r_mutex_lock (RMutex *mutex)
	Acquire mutex, blocking until available.
rboolean	r_mutex_trylock (RMutex *mutex)
	Try to acquire mutex without blocking; TRUE on success.
void	r_mutex_unlock (RMutex *mutex)
	Release mutex; the calling thread must currently hold it.
Recursive mutex
Identical contract to RMutex except the owning thread can lock the same mutex repeatedly; each _lock must be paired with a matching _unlock.
void	r_rmutex_init (RRMutex *mutex)
	Initialise a fresh RRMutex.
void	r_rmutex_clear (RRMutex *mutex)
	Release OS resources held by mutex.
void	r_rmutex_lock (RRMutex *mutex)
	Acquire mutex (recursively for the owning thread).
rboolean	r_rmutex_trylock (RRMutex *mutex)
	Try-lock variant; see r_mutex_trylock.
void	r_rmutex_unlock (RRMutex *mutex)
	Release one nesting level of mutex.
Read/write mutex
Many concurrent readers OR a single writer; writers exclude both readers and other writers.
void	r_rwmutex_init (RRWMutex *mutex)
	Initialise a fresh RRWMutex.
void	r_rwmutex_clear (RRWMutex *mutex)
	Release OS resources held by mutex.
void	r_rwmutex_rdlock (RRWMutex *mutex)
	Acquire a shared read lock; blocks until no writer holds the lock.
void	r_rwmutex_wrlock (RRWMutex *mutex)
	Acquire an exclusive write lock; blocks until no reader or writer holds the lock.
rboolean	r_rwmutex_tryrdlock (RRWMutex *mutex)
	Try-lock variant of r_rwmutex_rdlock.
rboolean	r_rwmutex_trywrlock (RRWMutex *mutex)
	Try-lock variant of r_rwmutex_wrlock.
void	r_rwmutex_rdunlock (RRWMutex *mutex)
	Release a previously-acquired read lock.
void	r_rwmutex_wrunlock (RRWMutex *mutex)
	Release a previously-acquired write lock.
Condition variable
void	r_cond_init (RCond *cond)
	Initialise a fresh RCond.
void	r_cond_clear (RCond *cond)
	Release OS resources held by cond.
void	r_cond_wait (RCond *cond, RMutex *mutex)
	Atomically release mutex and wait until signalled, then reacquire mutex before returning.
void	r_cond_signal (RCond *cond)
	Wake at least one thread waiting on cond.
void	r_cond_broadcast (RCond *cond)
	Wake all threads waiting on cond.

Threads
#define	r_thread_new(name, func, data)    r_thread_new_full (name, NULL, func, data)
	Convenience wrapper around r_thread_new_full with no CPU-affinity bitset.
#define	r_thread_ref   r_ref_ref
	Take a reference on thread (alias for r_ref_ref).
#define	r_thread_unref   r_ref_unref
	Drop a reference on thread (alias for r_ref_unref).
RThread *	r_thread_new_full (const rchar *name, const RBitset *cpuset, RThreadFunc func, rpointer data)
	Spawn a new thread running func(data).
rpointer	r_thread_join (RThread *thread)
	Wait for thread to terminate and return its result.
static void	r_thread_join_unref (rpointer thread)
	RDestroyNotify-compatible "join then unref" helper.
int	r_thread_kill (RThread *thread, int sig)
	Send signal sig to thread (POSIX-style; thin wrapper over pthread_kill on Unix).
const rchar *	r_thread_get_name (const RThread *thread)
	Return the human-readable name thread was given at creation.
ruint	r_thread_get_id (const RThread *thread)
	Return thread's OS-assigned numeric ID.
rboolean	r_thread_get_affinity (const RThread *thread, RBitset *cpuset)
	Read thread's current CPU-affinity bitset into cpuset.
rboolean	r_thread_set_affinity (RThread *thread, const RBitset *cpuset)
	Set thread's CPU-affinity mask.
RThread *	r_thread_current (void)
	Return the calling thread's RThread handle, or NULL if the calling thread was not created by rlib.
void	r_thread_exit (rpointer retval)
	Exit the calling thread, returning retval to its joiner.
void	r_thread_yield (void)
	Yield the calling thread's remaining quantum to the scheduler.
void	r_thread_sleep (ruint sec)
	Sleep the calling thread for sec whole seconds.
void	r_thread_usleep (rulong microsec)
	Sleep the calling thread for microsec microseconds.

Detailed Description

Threads, mutexes (plain, recursive, read/write), condition variables, thread-specific storage and one-shot initialisation.