Xenomai  3.1
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
semThe address of a semaphore descriptor filled in by the operation. Contents of this memory is undefined upon failure.
nameA valid NULL-terminated name which identifies the semaphore to bind to. This string should match the object name argument passed to rt_sem_create().
timeoutThe 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
semThe 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
semThe address of a semaphore descriptor which can be later used to identify uniquely the created object, upon success of this call.
nameAn 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.
icountThe initial value of the counting semaphore.
modeThe 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
semThe 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
semThe semaphore descriptor.
infoA 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
semThe semaphore descriptor.
timeoutA 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
semThe semaphore descriptor.
abs_timeoutAn 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
semThe semaphore descriptor.
abs_timeoutAn 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
semThe 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
semThe semaphore descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if sem is not a valid semaphore descriptor.
Tags
unrestricted