Semaphore services

Counting semaphore IPC mechanism. More...

Collaboration diagram for Semaphore services:

Data Structures
struct	RT_SEM_INFO
	Semaphore status descriptor. More...

Macros
#define	S_PRIO   0x1 /* Pend by task priority order. */
	Creation flags. More...

Functions
int	rt_sem_create (RT_SEM *sem, const char *name, unsigned long icount, int mode)
	Create a counting semaphore. More...
int	rt_sem_delete (RT_SEM *sem)
	Delete a semaphore. More...
int	rt_sem_p_timed (RT_SEM *sem, const struct timespec *abs_timeout)
	Pend on a semaphore. More...
static int	rt_sem_p_until (RT_SEM *sem, RTIME timeout)
	Pend on a semaphore (with absolute scalar timeout). More...
static int	rt_sem_p (RT_SEM *sem, RTIME timeout)
	Pend on a semaphore (with relative scalar timeout). More...
int	rt_sem_v (RT_SEM *sem)
	Signal a semaphore. More...
int	rt_sem_broadcast (RT_SEM *sem)
	Broadcast a semaphore. More...
int	rt_sem_inquire (RT_SEM *sem, RT_SEM_INFO *info)
	Query semaphore status. More...
int	rt_sem_bind (RT_SEM *sem, const char *name, RTIME timeout)
	Bind to a semaphore. More...
int	rt_sem_unbind (RT_SEM *sem)
	Unbind from a semaphore. More...

Detailed Description

Counting semaphore IPC mechanism.

A counting semaphore is a synchronization object for controlling the concurrency level allowed in accessing a resource from multiple real-time tasks, based on the value of a count variable accessed atomically. The semaphore is used through the P ("Proberen", from the Dutch "test and decrement") and V ("Verhogen", increment) operations. The P operation decrements the semaphore count by one if non-zero, or waits until a V operation is issued by another task. Conversely, the V operation releases a resource by incrementing the count by one, unblocking the heading task waiting on the P operation if any. Waiting on a semaphore may cause a priority inversion.

If no more than a single resource is made available at any point in time, the semaphore enforces mutual exclusion and thus can be used to serialize access to a critical section. However, mutexes should be used instead in order to prevent priority inversions, based on the priority inheritance protocol.

Macro Definition Documentation

S_PRIO

#define S_PRIO   0x1 /* Pend by task priority order. */

Creation flags.

Referenced by rt_sem_create().

Function Documentation

rt_sem_bind()

int rt_sem_bind	(	RT_SEM *	sem,
		const char *	name,
		RTIME	timeout
	)

Bind to a semaphore.

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

Parameters

sem	The address of a semaphore descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the semaphore to bind to. This string should match the object name argument passed to rt_sem_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_sem_broadcast()

int rt_sem_broadcast

(

RT_SEM *

sem

)

Broadcast a semaphore.

All tasks currently waiting on the semaphore are immediately unblocked. The semaphore count is set to zero.

Parameters

sem	The semaphore descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a valid semaphore descriptor.

Tags

unrestricted

rt_sem_create()

int rt_sem_create	(	RT_SEM *	sem,
		const char *	name,
		unsigned long	icount,
		int	mode
	)

Create a counting semaphore.

Parameters

sem	The address of a semaphore 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 semaphore. When non-NULL and non-empty, a copy of this string is used for indexing the created semaphore into the object registry.
icount	The initial value of the counting semaphore.
mode	The semaphore creation mode. The following flags can be OR'ed into this bitmask:

• S_FIFO makes tasks pend in FIFO order on the semaphore.
• S_PRIO makes tasks pend in priority order on the semaphore.
• S_PULSE causes the semaphore to behave in "pulse" mode. In this mode, the V (signal) operation attempts to release a single waiter each time it is called, without incrementing the semaphore count, even if no waiter is pending. For this reason, the semaphore count in pulse mode remains zero.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if icount is non-zero and S_PULSE is set in mode, or mode is otherwise invalid.
• -ENOMEM is returned if the system fails to get memory from the main heap in order to create the semaphore.
• -EEXIST is returned if the name is conflicting with an already registered semaphore.
• -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

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

References S_PRIO.

rt_sem_delete()

int rt_sem_delete

(

RT_SEM *

sem

)

Delete a semaphore.

This routine deletes a semaphore previously created by a call to rt_sem_create().

Parameters

sem	The semaphore descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a valid semaphore descriptor.
• -EPERM is returned if this service was called from an asynchronous context.

Tags

mode-unrestricted, switch-secondary

rt_sem_inquire()

int rt_sem_inquire	(	RT_SEM *	sem,
		RT_SEM_INFO *	info
	)

Query semaphore status.

This routine returns the status information about the specified semaphore.

Parameters

sem	The semaphore 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 sem is not a valid semaphore descriptor.

Tags

unrestricted

rt_sem_p()

int rt_sem_p ( RT_SEM *  sem, RTIME  timeout  )

inlinestatic

Pend on a semaphore (with relative scalar timeout).

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

Parameters

sem	The semaphore descriptor.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until the request is satisfied. Passing TM_NONBLOCK causes the service to return without blocking in case the request cannot be satisfied immediately.

Tags

xthread-nowait, switch-primary

rt_sem_p_timed()

int rt_sem_p_timed	(	RT_SEM *	sem,
		const struct timespec *	abs_timeout
	)

Pend on a semaphore.

Test and decrement the semaphore count. If the semaphore value is greater than zero, it is decremented by one and the service immediately returns to the caller. Otherwise, the caller is blocked until the semaphore is either signaled or destroyed, unless a non-blocking operation was required.

Parameters

sem	The semaphore descriptor.
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for the request to be satisfied (see note). Passing NULL causes the caller to block indefinitely until the request is satisfied. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return without blocking in case the request cannot be satisfied immediately.

Returns

Zero is returned upon success. Otherwise:

• -ETIMEDOUT is returned if abs_timeout is reached before the request is satisfied.
• -EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and the semaphore count is zero on entry.
• -EINTR is returned if rt_task_unblock() was called for the current task before the request is satisfied.
• -EINVAL is returned if sem is not a valid semaphore descriptor.
• -EIDRM is returned if sem is deleted while the caller was sleeping on it. In such a case, sem 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-nowait, 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_sem_p_until()

int rt_sem_p_until ( RT_SEM *  sem, RTIME  abs_timeout  )

inlinestatic

Pend on a semaphore (with absolute scalar timeout).

This routine is a variant of rt_sem_p_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

sem	The semaphore descriptor.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until the request is satisfied. Passing TM_NONBLOCK causes the service to return without blocking in case the request cannot be satisfied immediately.

Tags

xthread-nowait, switch-primary

rt_sem_unbind()

int rt_sem_unbind

(

RT_SEM *

sem

)

Unbind from a semaphore.

Parameters

sem	The semaphore descriptor.

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

Tags

thread-unrestricted

rt_sem_v()

int rt_sem_v

(

RT_SEM *

sem

)

Signal a semaphore.

If the semaphore is pended, the task heading the wait queue is immediately unblocked. Otherwise, the semaphore count is incremented by one, unless the semaphore is used in "pulse" mode (see rt_sem_create()).

Parameters

sem	The semaphore descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if sem is not a valid semaphore descriptor.

Tags

unrestricted