Condition variable services

POSIXish condition variable mechanism. More...

Collaboration diagram for Condition variable services:

Data Structures
struct	RT_COND_INFO
	Condition variable status descriptor. More...

Functions
int	rt_cond_create (RT_COND *cond, const char *name)
	Create a condition variable. More...
int	rt_cond_delete (RT_COND *cond)
	Delete a condition variable. More...
int	rt_cond_signal (RT_COND *cond)
	Signal a condition variable. More...
int	rt_cond_broadcast (RT_COND *cond)
	Broadcast a condition variable More...
int	rt_cond_wait_timed (RT_COND *cond, RT_MUTEX *mutex, const struct timespec *abs_timeout)
	Wait on a condition variable. More...
static int	rt_cond_wait_until (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
	Wait on a condition variable (with absolute scalar timeout). More...
static int	rt_cond_wait (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
	Wait on a condition variable (with relative scalar timeout). More...
int	rt_cond_inquire (RT_COND *cond, RT_COND_INFO *info)
	Query condition variable status. More...
int	rt_cond_bind (RT_COND *cond, const char *name, RTIME timeout)
	Bind to a condition variable. More...
int	rt_cond_unbind (RT_COND *cond)
	Unbind from a condition variable. More...

Detailed Description

POSIXish condition variable mechanism.

A condition variable is a synchronization mechanism which allows tasks to suspend execution until some predicate on some arbitrary shared data is satisfied.

The basic operations on conditions are: signal the condition (when the predicate becomes true), and wait for the condition, blocking the task execution until another task signals the condition. A condition variable must always be associated with a mutex, to avoid a well-known race condition where a task prepares to wait on a condition variable and another task signals the condition just before the first task actually waits on it.

Function Documentation

rt_cond_bind()

int rt_cond_bind	(	RT_COND *	cond,
		const char *	name,
		RTIME	timeout
	)

Bind to a condition variable.

This routine creates a new descriptor to refer to an existing condition variable identified by its symbolic name. If the object not exist on entry, the caller may block until a condition variable of the given name is created.

Parameters

cond	The address of a condition variable descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the condition variable to bind to. This string should match the object name argument passed to rt_cond_create().
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns

Zero is returned upon success. Otherwise:

• -EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
• -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
• -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
• -EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags

xthread-nowait, switch-primary

Note

The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

rt_cond_broadcast()

int rt_cond_broadcast

(

RT_COND *

cond

)

Broadcast a condition variable

All tasks currently waiting on the condition variable are immediately unblocked.

Parameters

cond	The condition variable descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if cond is not a valid condition variable descriptor.

Tags

unrestricted, switch-primary

rt_cond_create()

int rt_cond_create	(	RT_COND *	cond,
		const char *	name
	)

Create a condition variable.

Create a synchronization object which allows tasks to suspend execution until some predicate on shared data is satisfied.

Parameters

cond	The address of a condition variable descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the condition variable. When non-NULL and non-empty, a copy of this string is used for indexing the created condition variable into the object registry.

Returns

Zero is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get memory from the main heap in order to create the condition variable.
• -EEXIST is returned if the name is conflicting with an already registered condition variable.
• -EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.

Tags

xthread-only, mode-unrestricted, switch-secondary

Note

Condition variables can be shared by multiple processes which belong to the same Xenomai session.

Attention

If the underlying threading library does not support pthread_condattr_setclock(), timings with Alchemy condition variables will be based on CLOCK_REALTIME, and may therefore be affected by updates to the system date (e.g. NTP). This typically concerns legacy setups based on the linuxthreads library. In the normal case, timings are based on CLOCK_MONOTONIC.

rt_cond_delete()

int rt_cond_delete

(

RT_COND *

cond

)

Delete a condition variable.

This routine deletes a condition variable object previously created by a call to rt_cond_create().

Parameters

cond	The condition variable descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if alarm is not a valid condition variable descriptor.
• -EPERM is returned if this service was called from an asynchronous context.
• -EBUSY is returned upon an attempt to destroy the object referenced by cond while it is referenced (for example, while being used in a rt_cond_wait(), rt_cond_wait_timed() or rt_cond_wait_until() by another task).

Tags

mode-unrestricted, switch-secondary

rt_cond_inquire()

int rt_cond_inquire	(	RT_COND *	cond,
		RT_COND_INFO *	info
	)

Query condition variable status.

This routine returns the status information about the specified condition variable.

Parameters

cond	The condition variable descriptor.
info	A pointer to the return buffer" to copy the information to.

Returns

Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:

• -EINVAL is returned if cond is not a valid condition variable descriptor.

Tags

unrestricted, switch-primary

rt_cond_signal()

int rt_cond_signal

(

RT_COND *

cond

)

Signal a condition variable.

If the condition variable cond is pended, this routine immediately unblocks the first waiting task (by queuing priority order).

Parameters

cond	The condition variable descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if cond is not a valid condition variable descriptor.

Tags

unrestricted, switch-primary

rt_cond_unbind()

int rt_cond_unbind

(

RT_COND *

cond

)

Unbind from a condition variable.

Parameters

cond	The condition variable descriptor.

This routine releases a previous binding to a condition variable. After this call has returned, the descriptor is no more valid for referencing this object.

Tags

thread-unrestricted

rt_cond_wait()

int rt_cond_wait ( RT_COND *  cond, RT_MUTEX *  mutex, RTIME  timeout  )

inlinestatic

Wait on a condition variable (with relative scalar timeout).

This routine is a variant of rt_cond_wait_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

cond	The condition variable descriptor.
mutex	The address of the mutex serializing the access to the shared data.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely. Passing TM_NONBLOCK causes the caller to return immediately without block.

Tags

xthread-only, switch-primary

rt_cond_wait_timed()

int rt_cond_wait_timed	(	RT_COND *	cond,
		RT_MUTEX *	mutex,
		const struct timespec *	abs_timeout
	)

Wait on a condition variable.

This service atomically releases the mutex and blocks the calling task, until the condition variable cond is signaled or a timeout occurs, whichever comes first. The mutex is re-acquired before returning from this service.

Parameters

cond	The condition variable descriptor.
mutex	The address of the mutex serializing the access to the shared data.
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for the condition variable to be signaled (see note). Passing NULL causes the caller to block indefinitely. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the caller to return immediately without block.

Returns

Zero is returned upon success. Otherwise:

• -ETIMEDOUT is returned if abs_timeout is reached before the condition variable is signaled.
• -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } .
• -EINTR is returned if rt_task_unblock() was called for the current task.
• -EINVAL is returned if cond is not a valid condition variable descriptor.
• -EIDRM is returned if cond is deleted while the caller was waiting on the condition variable. In such event, cond is no more valid upon return of this service.
• -EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags

xthread-only, switch-primary

Note

abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

rt_cond_wait_until()

int rt_cond_wait_until ( RT_COND *  cond, RT_MUTEX *  mutex, RTIME  abs_timeout  )

inlinestatic

Wait on a condition variable (with absolute scalar timeout).

This routine is a variant of rt_cond_wait_timed() accepting an abs_timeout specification expressed as a scalar value.

Parameters

cond	The condition variable descriptor.
mutex	The address of the mutex serializing the access to the shared data.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely. Passing TM_NONBLOCK causes the caller to return immediately without block.

Tags

xthread-only, switch-primary