Cobalt/POSIX condition variable services. More...

Collaboration diagram for Condition variables:

Functions
int	pthread_cond_init (pthread_cond_t cond, const pthread_condattr_t attr)
	Initialize a condition variable More...

int	pthread_cond_destroy (pthread_cond_t *cond)
	Destroy a condition variable More...

int	pthread_cond_wait (pthread_cond_t cond, pthread_mutex_t mutex)
	Wait on a condition variable. More...

int	pthread_cond_timedwait (pthread_cond_t cond, pthread_mutex_t mutex, const struct timespec *abstime)
	Wait a bounded time on a condition variable. More...

int	pthread_cond_signal (pthread_cond_t *cond)
	Signal a condition variable. More...

int	pthread_cond_broadcast (pthread_cond_t *cond)
	Broadcast a condition variable. More...

int	pthread_condattr_init (pthread_condattr_t *attr)
	Initialize a condition variable attributes object. More...

int	pthread_condattr_destroy (pthread_condattr_t *attr)
	Destroy a condition variable attributes object. More...

int	pthread_condattr_getclock (const pthread_condattr_t attr, clockid_t clk_id)
	Get the clock selection attribute from a condition variable attributes object. More...

int	pthread_condattr_setclock (pthread_condattr_t *attr, clockid_t clk_id)
	Set the clock selection attribute of a condition variable attributes object. More...

int	pthread_condattr_getpshared (const pthread_condattr_t attr, int pshared)
	Get the process-shared attribute from a condition variable attributes object. More...

int	pthread_condattr_setpshared (pthread_condattr_t *attr, int pshared)
	Set the process-shared attribute of a condition variable attributes object. More...

Detailed Description

Cobalt/POSIX condition variable services.

A condition variable is a synchronization object that allows threads to suspend execution until some predicate on shared data is satisfied. The basic operations on conditions are: signal the condition (when the predicate becomes true), and wait for the condition, suspending the thread execution until another thread signals the condition.

A condition variable must always be associated with a mutex, to avoid the race condition where a thread prepares to wait on a condition variable and another thread signals the condition just before the first thread actually waits on it.

Before it can be used, a condition variable has to be initialized with pthread_cond_init(). An attribute object, which reference may be passed to this service, allows to select the features of the created condition variable, namely the clock used by the pthread_cond_timedwait() service (CLOCK_REALTIME is used by default), and whether it may be shared between several processes (it may not be shared by default, see pthread_condattr_setpshared()).

Note that pthread_cond_init() should be used to initialize a condition variable, using the static initializer PTHREAD_COND_INITIALIZER will delay the initialization to the first method called on the condition variable and will most likely introduce switches to secondary mode. The documentation (and specifically api-tags) of the condition variable services assumes the condition variable was explicitly initialised with pthread_cond_init().

Function Documentation

◆ pthread_cond_broadcast()

int pthread_cond_broadcast ( pthread_cond_t * cond )

Broadcast a condition variable.

This service unblocks all threads blocked on the condition variable cnd.

Parameters

cond	the condition variable to be signalled.

Returns

0 on succes,

an error number if:

EINVAL, the condition variable is invalid;
EPERM, the condition variable is not process-shared and does not belong to the current process.

See also: Specification.

Tags: xthread-only

◆ pthread_cond_destroy()

int pthread_cond_destroy ( pthread_cond_t * cond )

Destroy a condition variable

This service destroys the condition variable cond, if no thread is currently blocked on it. The condition variable becomes invalid for all condition variable services (they all return the EINVAL error) except pthread_cond_init().

Parameters

cond	the condition variable to be destroyed.

Returns

0 on succes,

an error number if:

EINVAL, the condition variable cond is invalid;
EPERM, the condition variable is not process-shared and does not belong to the current process;
EBUSY, some thread is currently using the condition variable.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_cond_init()

int pthread_cond_init	(	pthread_cond_t *	cond,
		const pthread_condattr_t *	attr
	)

Initialize a condition variable

This service initializes the condition variable cond, using the condition variable attributes object attr. If attr is NULL, default attributes are used (see pthread_condattr_init()).

Parameters

cond	the condition variable to be initialized;
attr	the condition variable attributes object.

Returns

0 on succes,

an error number if:

EINVAL, the condition variable attributes object attr is invalid or uninitialized;
EBUSY, the condition variable cond was already initialized;
ENOMEM, insufficient memory available from the system heap to initialize the condition variable, increase CONFIG_XENO_OPT_SYS_HEAPSZ.
EAGAIN, no registry slot available, check/raise CONFIG_XENO_OPT_REGISTRY_NRSLOTS.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_cond_signal()

int pthread_cond_signal ( pthread_cond_t * cond )

Signal a condition variable.

This service unblocks one thread blocked on the condition variable cnd.

If more than one thread is blocked on the specified condition variable, the highest priority thread is unblocked.

Parameters

cond	the condition variable to be signalled.

Returns

0 on succes,

an error number if:

EINVAL, the condition variable is invalid;
EPERM, the condition variable is not process-shared and does not belong to the current process.

See also: Specification.

Tags: xthread-only

◆ pthread_cond_timedwait()

int pthread_cond_timedwait	(	pthread_cond_t *	cond,
		pthread_mutex_t *	mutex,
		const struct timespec *	abstime
	)

Wait a bounded time on a condition variable.

This service is equivalent to pthread_cond_wait(), except that the calling thread remains blocked on the condition variable cnd only until the timeout specified by abstime expires.

The timeout abstime is expressed as an absolute value of the clock attribute passed to pthread_cond_init(). By default, CLOCK_REALTIME is used.

Parameters

cond	the condition variable to wait for;
mutex	the mutex associated with cnd;
abstime	the timeout, expressed as an absolute value of the clock attribute passed to pthread_cond_init().

Returns

0 on success,

an error number if:

EPERM, the caller context is invalid;
EPERM, the specified condition variable is not process-shared and does not belong to the current process;
EINVAL, the specified condition variable, mutex or timeout is invalid;
EINVAL, another thread is currently blocked on cnd using another mutex than mx;
EPERM, the specified mutex is not owned by the caller;
ETIMEDOUT, the specified timeout expired.

See also: Specification.

Tags: xthread-only, switch-primary

◆ pthread_cond_wait()

int pthread_cond_wait	(	pthread_cond_t *	cond,
		pthread_mutex_t *	mutex
	)

Wait on a condition variable.

This service atomically unlocks the mutex mx, and block the calling thread until the condition variable cnd is signalled using pthread_cond_signal() or pthread_cond_broadcast(). When the condition is signaled, this service re-acquire the mutex before returning.

Spurious wakeups occur if a signal is delivered to the blocked thread, so, an application should not assume that the condition changed upon successful return from this service.

Even if the mutex mx is recursive and its recursion count is greater than one on entry, it is unlocked before blocking the caller, and the recursion count is restored once the mutex is re-acquired by this service before returning.

Once a thread is blocked on a condition variable, a dynamic binding is formed between the condition vairable cnd and the mutex mx; if another thread calls this service specifying cnd as a condition variable but another mutex than mx, this service returns immediately with the EINVAL status.

This service is a cancellation point for Cobalt threads (created with the pthread_create() service). When such a thread is cancelled while blocked in a call to this service, the mutex mx is re-acquired before the cancellation cleanup handlers are called.

Parameters

cond	the condition variable to wait for;
mutex	the mutex associated with cnd.

Returns

0 on success,

an error number if:

EPERM, the caller context is invalid;
EINVAL, the specified condition variable or mutex is invalid;
EPERM, the specified condition variable is not process-shared and does not belong to the current process;
EINVAL, another thread is currently blocked on cnd using another mutex than mx;
EPERM, the specified mutex is not owned by the caller.

See also: Specification.

Tags: xthread-only, switch-primary

◆ pthread_condattr_destroy()

int pthread_condattr_destroy ( pthread_condattr_t * attr )

Destroy a condition variable attributes object.

This service destroys the condition variable attributes object attr. The object becomes invalid for all condition variable services (they all return EINVAL) except pthread_condattr_init().

Parameters

attr	the initialized mutex attributes object to be destroyed.

Returns

0 on success;

an error number if:

EINVAL, the mutex attributes object attr is invalid.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_condattr_getclock()

int pthread_condattr_getclock	(	const pthread_condattr_t *	attr,
		clockid_t *	clk_id
	)

Get the clock selection attribute from a condition variable attributes object.

This service stores, at the address clk_id, the value of the clock attribute in the condition variable attributes object attr.

See pthread_cond_timedwait() for a description of the effect of this attribute on a condition variable. The clock ID returned is CLOCK_REALTIME or CLOCK_MONOTONIC.

Parameters

attr	an initialized condition variable attributes object,
clk_id	address where the clock attribute value will be stored on success.

Returns

0 on success,

an error number if:

EINVAL, the attribute object attr is invalid.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_condattr_getpshared()

int pthread_condattr_getpshared	(	const pthread_condattr_t *	attr,
		int *	pshared
	)

Get the process-shared attribute from a condition variable attributes object.

This service stores, at the address pshared, the value of the pshared attribute in the condition variable attributes object attr.

The pshared attribute may only be one of PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED. See pthread_condattr_setpshared() for the meaning of these two constants.

Parameters

attr	an initialized condition variable attributes object.
pshared	address where the value of the pshared attribute will be stored on success.

Returns

0 on success,

an error number if:

EINVAL, the pshared address is invalid;
EINVAL, the condition variable attributes object attr is invalid.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_condattr_init()

int pthread_condattr_init ( pthread_condattr_t * attr )

Initialize a condition variable attributes object.

This services initializes the condition variable attributes object attr with default values for all attributes. Default value are:

for the clock attribute, CLOCK_REALTIME;
for the pshared attribute PTHREAD_PROCESS_PRIVATE.

If this service is called specifying a condition variable attributes object that was already initialized, the attributes object is reinitialized.

Parameters

attr	the condition variable attributes object to be initialized.

Returns

0 on success;

an error number if:

ENOMEM, the condition variable attribute object pointer attr is NULL.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_condattr_setclock()

int pthread_condattr_setclock	(	pthread_condattr_t *	attr,
		clockid_t	clk_id
	)

Set the clock selection attribute of a condition variable attributes object.

This service set the clock attribute of the condition variable attributes object attr.

See pthread_cond_timedwait() for a description of the effect of this attribute on a condition variable.

Parameters

attr	an initialized condition variable attributes object,
clk_id	value of the clock attribute, may be CLOCK_REALTIME or CLOCK_MONOTONIC.

Returns

0 on success,

an error number if:

EINVAL, the condition variable attributes object attr is invalid;
EINVAL, the value of clk_id is invalid for the clock attribute.

See also: Specification.

Tags: thread-unrestricted

◆ pthread_condattr_setpshared()

int pthread_condattr_setpshared	(	pthread_condattr_t *	attr,
		int	pshared
	)

Set the process-shared attribute of a condition variable attributes object.

This service set the pshared attribute of the condition variable attributes object attr.

Parameters

attr an initialized condition variable attributes object.

pshared

value of the pshared attribute, may be one of:

PTHREAD_PROCESS_PRIVATE, meaning that a condition variable created with the attributes object attr will only be accessible by threads within the same process as the thread that initialized the condition variable;
PTHREAD_PROCESS_SHARED, meaning that a condition variable created with the attributes object attr will be accessible by any thread that has access to the memory where the condition variable is allocated.

Returns

0 on success,

an error status if:

EINVAL, the condition variable attributes object attr is invalid;
EINVAL, the value of pshared is invalid.

See also: Specification.

Tags: thread-unrestricted

Functions

Detailed Description

Function Documentation

◆ pthread_cond_broadcast()

◆ pthread_cond_destroy()

◆ pthread_cond_init()

◆ pthread_cond_signal()

◆ pthread_cond_timedwait()

◆ pthread_cond_wait()

◆ pthread_condattr_destroy()

◆ pthread_condattr_getclock()

◆ pthread_condattr_getpshared()

◆ pthread_condattr_init()

◆ pthread_condattr_setclock()

◆ pthread_condattr_setpshared()