NAME

rt_sem_init - initialize a semaphore

SYNOPSIS

#include "rtai_sched.h"

void rt_sem_init (SEM* sem, int value);

DESCRIPTION

rt_sem_init initializes a semaphore sem. A semaphore can be used for communication and synchronization among real-time tasks.

sem must point to a statically allocated structure. value is the initial value of the semaphore (usually 1).

Positive value of the semaphore variable shows how many tasks can do a 'P' operation without blocking. (Say how many tasks can enter the critical region.) Negative value of a semaphore shows that how many task is blocked on it. (Unless it is initialized to negative in advance but this would be totally senseless).

RETURN VALUE

None

ERRORS

None

BUGS

Negative initial values should not be allowed.

NOTE

Just for curiosity: the explanation of "P" and "V":
The name of P operation comes the Dutch "prolagen", a combination of "proberen" (to try) and "verlagen" (to reduce); Also from the word "passeren" (to pass).

The name of V operation coimes from the Dutch "verhogen" (to increase) or "vrygeven" (to release).

(Source: Daniel Tabak - Multiprocessors, Prentice Hall, 1990.)

[return to index]

NAME

rt_sem_delete - delete a semaphore

SYNOPSIS

#include "rtai_sched.h"

int rt_sem_delete (SEM* sem);

DESCRIPTION

rt_sem_delete deletes a semaphore previously created with rt_sem_create.

sem points to the structure used in the corresponding call to rt_sem_create.

Any tasks blocked on this semaphore is allowed to run when semaphore is destroyed.

RETURN VALUE

On success, 0 is returned. On failure, a nonzero value is returned, as described below.

ERRORS

0xffff
sem does not refer to a valid semaphore.

BUGS

-EINVAL would be more a consistent error code.

[return to index]

NAME

rt_sem_signal - signalling a semaphore

SYNOPSIS

#include "rtai_sched.h"

int rt_sem_signal (SEM* sem);

DESCRIPTION

rt_sem_signal is the semaphore post (sometimes known as 'give', 'signal', or 'V') operation. It is tipically called when the task leaves a critical region. The semaphore value is incremented and tested. If the value is not positive, the first task in semaphore's waiting queue is allowed to run. rt_sem_signal does not block the caller task.

sem points to the structure used in the call to rt_sem_create.

RETURN VALUE

On success, 0 is returned. On failure, a nonzero value is returned as described below.

ERRORS

0xffff
sem does not refer to a valid semaphore.

BUGS

-EINVAL would be more a consistent error code.

[return to index]

NAME

rt_sem_wait - wait a semaphore

SYNOPSIS

#include "rtai_sched.h"

int rt_sem_wait (SEM* sem);

DESCRIPTION

rt_sem_wait is the semaphore wait (sometimes known as 'take' or 'P') operation. It is tipically called when a task enters a critical region. The semaphore value is decremented and tested. If it is still non-negative rt_sem_wait returns immediately. Otherwise the caller task is blocked and queued up. Queueing may happen in priority order or on FIFO base. This is determined by compile time option SEM_PRIORD. In this case rt_sem_wait returns if

sem points to the structure used in the call to rt_sem_create.

RETURN VALUE

On success an undetermined number is returned. (Actually the return value somehow depends on the semaphore value.)
On failure, a special value is returned as described below.

ERRORS

0xffff
sem does not refer to a valid semaphore.

BUGS

The normal return value should not depend on the current value of the semaphore. In the current implementation number 0xffff can be returned under normal circumstances too and it is undistinguishable from the error code.

[return to index]

NAME

rt_sem_wait_if - take a semaphore if possible

SYNOPSIS

#include "rtai_sched.h"

int rt_sem_wait_if (SEM* sem);

DESCRIPTION

rt_sem_wait_if is a version of the semaphore wait (sometimes known as 'take' or 'P') operation. It is similar to rt_sem_wait but it is never blocks the caller. If the semaphore is not free, rt_sem_wait_if returns immediately and the semaphore value remains unchanged.

RETURN VALUE

On failure a special value is returned as described below. Otherwise the return value is undetermined. (Actually it is somehow derived from the current value of the semaphore.)

ERRORS

0xffff
sem does not refer to a valid semaphore.

BUGS

The normal return value should not depend on the current value of the semaphore. In the current implementation number 0xffff can be returned under normal circumstances too and it is undistinguishable from the error code. Moreover the caller cannot figure out, whether if taking the semaphore was successful or not.

[return to index]

NAME

rt_sem_wait_until, rt_sem_wait_timed - wait a semaphore with timeout

SYNOPSIS

#include "rtai_sched.h"

int rt_sem_wait_until (SEM* sem, RTIME time);

int rt_sem_wait_timed (SEM* sem, RTIME delay);

DESCRIPTION

rt_sem_wait_until and rt_sem_wait_timed are version of the semaphore wait (sometimes known as 'take' or 'P') operation. The semaphore value is decremented and tested. If it is still non-negative these functions return immediately. Otherwise the caller task is blocked and queued up. Queueing may happen in priority order or on FIFO base. This is determined by compile time option SEM_PRIORD. In this case these functions return if In case of timeout the semaphore value is incremented before return.
time is an absolute value. delay is relative to the current time.

RETURN VALUE

On failure a special value is returned as described below. Otherwise the return value is undetermined. (Actually it is somehow derived from the current value of the semaphore.)

ERRORS

0xffff
sem does not refer to a valid semaphore.

BUGS

The normal return value should not depend on the current value of the semaphore. In the current implementation number 0xffff can be returned under normal circumstances too and it is undistinguishable from the error code. Moreover the caller cannot figure out, whether if taking the semaphore was successful or not.

[return to index]