Threads, locks and condition variables

OS-thread spawning, mutex / RW-mutex / condition-variable primitives, and thread-specific storage. More...

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

Detailed Description

OS-thread spawning, mutex / RW-mutex / condition-variable primitives, and thread-specific storage.

The pointer-typed RMutex / RRMutex / RRWMutex / RCond carry an opaque OS handle; they must be initialised before use with the matching _init call and torn down with _clear.

Function Documentation

r_cond_wait()

void r_cond_wait	(	RCond *	cond,
		RMutex *	mutex
	)

Atomically release mutex and wait until signalled, then reacquire mutex before returning.

Spurious wake-ups are possible; callers must recheck their predicate in a loop.

r_thread_get_affinity()

rboolean r_thread_get_affinity	(	const RThread *	thread,
		RBitset *	cpuset
	)

Read thread's current CPU-affinity bitset into cpuset.

Returns

TRUE on success, FALSE if the OS does not support it.

r_thread_join()

rpointer r_thread_join

(

RThread *

thread

)

Wait for thread to terminate and return its result.

Joining is one-shot per thread; calling twice on the same thread is undefined.

r_thread_join_unref()

static void r_thread_join_unref ( rpointer  thread )

inlinestatic

RDestroyNotify-compatible "join then unref" helper.

Useful for RSList / RPtrArray destroy paths that should wait for the thread first. Discards the thread's return value.

r_thread_new_full()

RThread * r_thread_new_full	(	const rchar *	name,
		const RBitset *	cpuset,
		RThreadFunc	func,
		rpointer	data
	)

Spawn a new thread running func(data).

Parameters

name	Optional human-readable name (for diagnostics and OS thread naming where available); may be NULL.
cpuset	Optional CPU-affinity mask; NULL leaves the OS default scheduling in place.
func	Entry point; its return value is returned by r_thread_join.
data	Opaque argument forwarded to func.

Returns

New RThread (refcounted), or NULL on failure.

r_thread_set_affinity()

rboolean r_thread_set_affinity	(	RThread *	thread,
		const RBitset *	cpuset
	)

Set thread's CPU-affinity mask.

Returns

TRUE on success, FALSE if the OS does not support it.

r_tss_get()

rpointer r_tss_get

(

RTss *

tss

)

Retrieve this thread's TSS value, or NULL if unset.

Parameters

tss	Persistent RTss declared with R_TSS_INIT.