Condition variable services.

Collaboration diagram for Condition variable services.:

Files
file	cond.c
	This file is part of the Xenomai project.
Functions
int	rt_cond_create (RT_COND *cond, const char *name)
	Create a condition variable.
int	rt_cond_delete (RT_COND *cond)
	Delete a condition variable.
int	rt_cond_signal (RT_COND *cond)
	Signal a condition variable.
int	rt_cond_broadcast (RT_COND *cond)
	Broadcast a condition variable.
int	rt_cond_wait (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
	Wait on a condition.
int	rt_cond_wait_until (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
	Wait on a condition (with absolute timeout date).
int	rt_cond_inquire (RT_COND *cond, RT_COND_INFO *info)
	Inquire about a condition variable.
int	rt_cond_bind (RT_COND *cond, const char *name, RTIME timeout)
	Bind to a condition variable.
static int	rt_cond_unbind (RT_COND *cond)
	Unbind from a condition variable.

---

Detailed Description

Condition variable services.

A condition variable is a synchronization object which allows tasks 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, 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

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

Bind to a condition variable.

This user-space only service retrieves the uniform descriptor of a given Xenomai condition variable identified by its symbolic name. If the condition variable does not exist on entry, this service blocks the caller until a condition variable of the given name is created.

Parameters:

name	A valid NULL-terminated name which identifies the condition variable to bind to.
cond	The address of a condition variable descriptor retrieved by the operation. Contents of this memory is undefined upon failure.
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:

0 is returned upon success. Otherwise:

• -EFAULT is returned if cond or name is referencing invalid memory.

• -EINTR is returned if rt_task_unblock() has been called for the waiting 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 called from a context which cannot sleep (e.g. interrupt, non-realtime context).

Environments:

This service can be called from:

• User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

int rt_cond_broadcast

(

RT_COND *

cond

)

Broadcast a condition variable.

If the condition variable is pended, all tasks currently waiting on it are immediately unblocked.

Parameters:

cond	The descriptor address of the affected condition variable.

Returns:

0 is returned upon success. Otherwise:

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

• -EIDRM is returned if cond is a deleted condition variable descriptor.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine
• Kernel-based task
• User-space task

Rescheduling: possible.

References xnpod_schedule(), and xnsynch_flush().

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

Create a condition variable.

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

Parameters:

cond	The address of a condition variable descriptor Xenomai will use to store the variable-related data. This descriptor must always be valid while the variable is active therefore it must be allocated in permanent memory.
name	An ASCII string standing for the symbolic name of the condition variable. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created variable.

Returns:

0 is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the condition variable.

• -EEXIST is returned if the name is already in use by some registered object.

• -EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: possible.

References rt_cond_delete(), xnregistry_enter(), and xnsynch_init().

int rt_cond_delete

(

RT_COND *

cond

)

Delete a condition variable.

Destroy a condition variable and release all the tasks currently pending on it. A condition variable exists in the system since rt_cond_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:

cond	The descriptor address of the affected condition variable.

Returns:

0 is returned upon success. Otherwise:

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

• -EIDRM is returned if cond is a deleted condition variable descriptor.

• -EPERM is returned if this service was called from an asynchronous context.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based task
• User-space task

Rescheduling: possible.

References xnpod_schedule(), and xnregistry_remove().

Referenced by rt_cond_create().

int rt_cond_inquire	(	RT_COND *	cond,
		RT_COND_INFO *	info
	)

Inquire about a condition variable.

Return various information about the status of a given condition variable.

Parameters:

cond	The descriptor address of the inquired condition variable.
info	The address of a structure the condition variable information will be written to.

Returns:

0 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 condition variable descriptor.

• -EIDRM is returned if cond is a deleted condition variable descriptor.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine
• Kernel-based task
• User-space task

Rescheduling: never.

int rt_cond_signal

(

RT_COND *

cond

)

Signal a condition variable.

If the condition variable is pended, the first waiting task (by queuing priority order) is immediately unblocked.

Parameters:

cond	The descriptor address of the affected condition variable.

Returns:

0 is returned upon success. Otherwise:

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

• -EIDRM is returned if cond is a deleted condition variable descriptor.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine
• Kernel-based task
• User-space task

Rescheduling: possible.

References xnpod_schedule(), and xnsynch_wakeup_one_sleeper().

int rt_cond_unbind

(

RT_COND *

cond

)

[inline, static]

Unbind from a condition variable.

This user-space only service unbinds the calling task from the condition variable object previously retrieved by a call to rt_cond_bind().

Parameters:

cond	The address of a condition variable descriptor to unbind from.

Returns:

0 is always returned.

This service can be called from:

• User-space task.

Rescheduling: never.

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

Wait on a condition.

This service atomically release the mutex and causes the calling task to block on the specified condition variable. The caller will be unblocked when the variable is signaled, and the mutex re-acquired before returning from this service.

Tasks pend on condition variables by priority order.

Parameters:

cond	The descriptor address of the affected condition variable.
mutex	The descriptor address of the mutex protecting the condition variable.
timeout	The number of clock ticks to wait for the condition variable to be signaled (see note). Passing TM_INFINITE causes the caller to block indefinitely until the condition variable is signaled.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if mutex is not a mutex descriptor, or cond is not a condition variable descriptor.

• -EIDRM is returned if mutex or cond is a deleted object descriptor, including if the deletion occurred while the caller was sleeping on the variable.

• -ETIMEDOUT is returned if timeout expired before the condition variable has been signaled.

• -EINTR is returned if rt_task_unblock() has been called for the waiting task, or a signal has been received before the condition variable has been signaled. Note that the condition variable may be signaled right after this interruption, so when using -EINTR, the code must not call rt_cond_wait() immediately again, or a condition signal may be missed. With respect to restartint rt_cond_wait(), -EINTR should be handled as if 0 had been returned.

• -EWOULDBLOCK is returned if timeout equals TM_NONBLOCK.

Environments:

This service can be called from:

• Kernel-based task
• User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

References pthread_cleanup_pop(), pthread_cleanup_push(), pthread_setcanceltype(), and pthread_testcancel().

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

Wait on a condition (with absolute timeout date).

This service atomically release the mutex and causes the calling task to block on the specified condition variable. The caller will be unblocked when the variable is signaled, and the mutex re-acquired before returning from this service.

Tasks pend on condition variables by priority order.

Parameters:

cond	The descriptor address of the affected condition variable.
mutex	The descriptor address of the mutex protecting the condition variable.
timeout	The absolute date specifying a time limit to wait for the condition variable to be signaled (see note). Passing TM_INFINITE causes the caller to block indefinitely until the condition variable is signaled.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if mutex is not a mutex descriptor, or cond is not a condition variable descriptor.

• -EIDRM is returned if mutex or cond is a deleted object descriptor, including if the deletion occurred while the caller was sleeping on the variable.

• -ETIMEDOUT is returned if the absolute timeout date is reached before the condition variable is signaled.

• -EINTR is returned if rt_task_unblock() has been called for the waiting task before the condition variable has been signaled. Note that the condition variable may be signaled right after this interruption, so when using -EINTR, the code must not call rt_cond_wait() immediately again, or a condition signal may be missed. With respect to restartint rt_cond_wait(), -EINTR should be handled as if 0 had been returned.

• -EWOULDBLOCK is returned if timeout equals TM_NONBLOCK.

Environments:

This service can be called from:

• Kernel-based task
• User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

References pthread_cleanup_pop(), pthread_cleanup_push(), pthread_setcanceltype(), and pthread_testcancel().