RTEMS 4.7.0 On-Line Library

Semaphore Manager SEMAPHORE_OBTAIN - Acquire a semaphore

RTEMS Ada User's Guide

9.4.4: SEMAPHORE_OBTAIN - Acquire a semaphore

CALLING SEQUENCE:

procedure Semaphore_Obtain (
   ID         : in     RTEMS.ID;
   Option_Set : in     RTEMS.Option;
   Timeout    : in     RTEMS.Interval;
   Result     :    out RTEMS.Status_Codes
);

DIRECTIVE STATUS CODES:

RTEMS.SUCCESSFUL - semaphore obtained successfully
RTEMS.UNSATISFIED - semaphore not available
RTEMS.TIMEOUT - timed out waiting for semaphore
RTEMS.OBJECT_WAS_DELETED - semaphore deleted while waiting
RTEMS.INVALID_ID - invalid semaphore id

DESCRIPTION:

This directive acquires the semaphore specified by id. The RTEMS.WAIT and RTEMS.NO_WAIT components of the options parameter indicate whether the calling task wants to wait for the semaphore to become available or return immediately if the semaphore is not currently available. With either RTEMS.WAIT or RTEMS.NO_WAIT, if the current semaphore count is positive, then it is decremented by one and the semaphore is successfully acquired by returning immediately with a successful return code.

If the calling task chooses to return immediately and the current semaphore count is zero or negative, then a status code is returned indicating that the semaphore is not available. If the calling task chooses to wait for a semaphore and the current semaphore count is zero or negative, then it is decremented by one and the calling task is placed on the semaphore's wait queue and blocked. If the semaphore was created with the RTEMS.PRIORITY attribute, then the calling task is inserted into the queue according to its priority. However, if the semaphore was created with the RTEMS.FIFO attribute, then the calling task is placed at the rear of the wait queue. If the binary semaphore was created with the RTEMS.INHERIT_PRIORITY attribute, then the priority of the task currently holding the binary semaphore is guaranteed to be greater than or equal to that of the blocking task. If the binary semaphore was created with the RTEMS.PRIORITY_CEILING attribute, a task successfully obtains the semaphore, and the priority of that task is greater than the ceiling priority for this semaphore, then the priority of the task obtaining the semaphore is elevated to that of the ceiling.

The timeout parameter specifies the maximum interval the calling task is willing to be blocked waiting for the semaphore. If it is set to RTEMS.NO_TIMEOUT, then the calling task will wait forever. If the semaphore is available or the RTEMS.NO_WAIT option component is set, then timeout is ignored.

NOTES:

The following semaphore acquisition option constants are defined by RTEMS:

RTEMS.WAIT - task will wait for semaphore (default)
RTEMS.NO_WAIT - task should not wait

Attempting to obtain a global semaphore which does not reside on the local node will generate a request to the remote node to access the semaphore. If the semaphore is not available and RTEMS.NO_WAIT was not specified, then the task must be blocked until the semaphore is released. A proxy is allocated on the remote node to represent the task until the semaphore is released.

A clock tick is required to support the timeout functionality of this directive.

RTEMS Ada User's Guide