Semaphore services.
[Native RTAI API.]


Detailed Description

Semaphore services.


Files

file  sem.c
 This file is part of the RTAI project.

Functions

int rt_sem_create (RT_SEM *sem, const char *name, unsigned long icount, int mode)
 Create a counting semaphore.
int rt_sem_delete (RT_SEM *sem)
 Delete a semaphore.
int rt_sem_p (RT_SEM *sem, RTIME timeout)
 Pend on a semaphore.
int rt_sem_v (RT_SEM *sem)
 Signal a semaphore.
int rt_sem_inquire (RT_SEM *sem, RT_SEM_INFO *info)
 Inquire about a semaphore.


Function Documentation

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 RTAI will use to store the semaphore-related data. This descriptor must always be valid while the semaphore is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the semaphore. 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 semaphore.
icount The initial value of the semaphore count.
mode The semaphore creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new semaphore:
  • S_FIFO makes tasks pend in FIFO order on the semaphore.

  • S_PRIO makes tasks pend in priority order on the semaphore.

Returns:
0 is returned upon success. Otherwise:
  • -EEXIST is returned if the name is already in use by some registered object.

Context: This routine can be called on behalf of a task or from the initialization code.

int rt_sem_delete RT_SEM *  sem  ) 
 

Delete a semaphore.

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

Parameters:
sem The descriptor address of the affected semaphore.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if sem is not a semaphore descriptor.

  • -EIDRM is returned if sem is a deleted semaphore descriptor.

Side-effect: This routine calls the rescheduling procedure if tasks have been woken up as a result of the deletion.

Context: This routine can always be called on behalf of a task, or from the initialization code.

int rt_sem_inquire RT_SEM *  sem,
RT_SEM_INFO *  info
 

Inquire about a semaphore.

Return various information about the status of a given semaphore.

Parameters:
sem The descriptor address of the inquired semaphore.
info The address of a structure the semaphore 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 sem is not a semaphore descriptor.

  • -EIDRM is returned if sem is a deleted semaphore descriptor.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_sem_p RT_SEM *  sem,
RTIME  timeout
 

Pend on a semaphore.

Acquire a semaphore unit. 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 has been required.

Parameters:
sem The descriptor address of the affected semaphore.
timeout The number of clock ticks to wait for a semaphore unit to be available (see note). Passing RT_TIME_INFINITE causes the caller to block indefinitely until a unit is available. Passing RT_TIME_NONBLOCK causes the service to return immediately without waiting if no unit is available.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if sem is not a semaphore descriptor.

  • -EIDRM is returned if sem is a deleted semaphore descriptor, including if the deletion occurred while the caller was sleeping on it for a unit to become available.

  • -EWOULDBLOCK is returned if timeout is equal to RT_TIME_NONBLOCK and the semaphore value is zero.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before a semaphore unit has become available.

  • -ETIMEDOUT is returned if no unit is available within the specified amount of time.

Side-effect: This routine calls the rescheduling procedure unless a semaphore unit is immediately available, or timeout specifies a non-blocking operation.

Context: This routine can be called on behalf of a task. It can also be called on behalf of an interrupt context or from the initialization code provided timeout is equal to RT_TIME_NONBLOCK.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in nanoseconds.

int rt_sem_v RT_SEM *  sem  ) 
 

Signal a semaphore.

Release a semaphore unit. If the semaphore is pended, the first waiting task (by queuing order) is immediately unblocked; otherwise, the semaphore value is incremented by one.

Parameters:
sem The descriptor address of the affected semaphore.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if sem is not a semaphore descriptor.

  • -EIDRM is returned if sem is a deleted semaphore descriptor.

Side-effect: This routine calls the rescheduling procedure if a task is woken up as a result of the operation.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8