_lwp_sema_init(S)

_lwp_sema_init -- initialize a semaphore

Synopsis

   #include <synch.h>
   
   int _lwp_sema_init(_lwp_sema_t *sema, int count);

Parameters

sema: pointer to semaphore to initialize
count: number of resources to be protected by the semaphore

Description

_lwp_sema_init initializes the semaphore sema to a known state. Once initialized, the semaphore can be used any number of times without being re-initialized. A semaphore should not be re-initialized while lightweight processes (LWPs) are waiting at the semaphore.

count parameter

count, which must be greater than or equal to zero, defines the initial count of resources protected by the semaphore. If count is 1, the semaphore will be a binary semaphore. If count is greater than 1, the semaphore will be a counting, or general, semaphore.

sema parameter

sema points to the semaphore to be initialized.

Return values

On success sema is initialized and the operation returns zero.

Errors

If any of the following conditions is detected, _lwp_sema_init fails and returns the corresponding value:

EINVAL: Invalid argument specified.

Usage

Conceptually, a semaphore is a non-negative integer count. Semaphores are typically used to coordinate access to resources. The semaphore count is initialized with _lwp_sema_init to the number of free resources. LWPs then atomically increment the count with _lwp_sema_post when resources are added and atomically decrement the count with _lwp_sema_wait when resources are removed. When the semaphore count becomes zero, indicating that no more resources are present, LWPs trying to decrement the semaphore with _lwp_sema_wait will block until the count becomes greater than zero.

Semaphores are classified as one of two types: binary or counting.

Binary semaphores (those that take on only values of 1 and 0) are similar in use and purpose to mutex locks: they typically are used to ensure that only one LWP at a time executes a critical section of code. When used before access to shared data, they guarantee the integrity of the data.

Counting or general semaphores (those with a count greater than 1) are typically used to protect a pool of resources.

Note that semaphores protect data only when the convention of calling _lwp_sema_wait and _lwp_sema_post is faithfully followed before and after any access of the data.

Warnings

_lwp_sema_init does not examine the sema argument before initializing it. If _lwp_sema_init is called more than once for the same semaphore, it will overwrite its state. It is the user's responsibility to ensure that _lwp_sema_init is only called once for each semaphore.

Operations on semaphores initialized with _lwp_sema_init are not recursive; an LWP can block itself if it attempts to reacquire a semaphore that it has already acquired.

References

_lwp_sema_post(S), _lwp_sema_wait(S), _lwp_sema_trywait(S), sema_destroy(SYNCH), sema_post(SYNCH), sema_trywait(SYNCH), sema_wait(SYNCH)

Notices

Lightweight processes (LWPs) are internal interfaces and are subject to change. Their use should be avoided.