One-shot initialisation

Run an init function exactly once across all threads, with a cheap fast path on every subsequent call. More...

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.

Detailed Description

Run an init function exactly once across all threads, with a cheap fast path on every subsequent call.

Macro Definition Documentation

R_ONCE_INIT

#define R_ONCE_INIT   { R_ONCE_STATE_INIT, NULL }

Static initialiser for an ROnce in INIT state.

Use as { static ROnce o = R_ONCE_INIT; } at file or block scope.

Typedef Documentation

RThreadFunc

typedef rpointer(* RThreadFunc) (rpointer data)

Thread entry-point signature.

Parameters

data	Opaque argument passed to r_thread_new_full.

Returns

Value the joiner receives from r_thread_join.

Enumeration Type Documentation

ROnceState

enum ROnceState

Lifecycle states of an ROnce.

The states transition INIT -> RUNNING -> DONE exactly once per ROnce instance, driven by the first r_call_once caller. They are an implementation detail of r_call_once and not intended for external use.

Enumerator
R_ONCE_STATE_INIT	Fresh, init function not yet started.
R_ONCE_STATE_RUNNING	Init function executing in some thread.
R_ONCE_STATE_DONE	Init function returned; ret is set.

Function Documentation

r_call_once()

rpointer r_call_once	(	ROnce *	once,
		RThreadFunc	f,
		rpointer	a
	)

Run f exactly once across all threads, return its result.

The first caller to win the state transition runs f with a and stores the returned pointer in once. All later callers, across all threads, get the cached pointer back without re-running f. Concurrent first-callers block until the running thread finishes.

The hot path (after init has settled) is a single atomic load and a branch, so it is cheap enough to call on every entry to a frequently-invoked function.

Parameters

once	Persistent ROnce instance, seeded with R_ONCE_INIT or zero-initialised.
f	Init function; called at most once per once.
a	Opaque argument forwarded to f.

Returns

The pointer f returned (cached after the first call).