Condition variable services.
[Native Xenomai API.]

Collaboration diagram for Condition variable services.:

---

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.

Files
file	cond.c
	This file is part of the Xenomai project.
Functions
int	rt_cond_create (RT_COND *cond, const char *name)
int	rt_cond_delete (RT_COND *cond)
int	rt_cond_signal (RT_COND *cond)
int	rt_cond_broadcast (RT_COND *cond)
int	rt_cond_wait (RT_COND *cond, RT_MUTEX *mutex, RTIME timeout)
int	rt_cond_inquire (RT_COND *cond, RT_COND_INFO *info)
int	rt_cond_bind (RT_COND *cond, const char *name, RTIME timeout)
static int	rt_cond_unbind (RT_COND *cond)

---

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 or scheduler locked).

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.

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.

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

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.

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.

• -EINTR is returned if rt_task_unblock() has been called for the waiting task before the condition variable has been signaled.

• -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.

---