semaphore(3synch)

semaphore: sema_destroy, sema_init, sema_post, sema_trywait, sema_wait -- overview of semaphore routines

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int sema_init(sema_t *sema, int sema_count, int type, void *arg);
   

   int sema_wait(sema_t *sema);
   

   int sema_trywait(sema_t *sema);
   

   int sema_post(sema_t *sema);
   

   int sema_destroy(sema_t *sema);

Description

Conceptually, a semaphore is a count of free resources. Semaphores are typically used to coordinate access to resources. The semaphore count is initialized with sema_init to the number of free resources. Threads then atomically increment the count with sema_post when resources are added and atomically decrement the count with sema_wait when resources are removed. When the semaphore count becomes zero, indicating that no more resources are present, threads trying to decrement the semaphore with sema_wait(3synch) will block until a resource becomes available.

If there is only one resource to protect (that is, the semaphore count will never be greater than one), a mutex lock will provide better performance than a semaphore.

Parameters

sema: pointer to semaphore to initialize, post, wait for, or destroy
sema_count: number of resources to be protected by the semaphore
type: USYNC_THREAD or USYNC_PROCESS
arg: NULL (reserved for future use)

Note that semaphores protect data only when the convention of calling sema_wait and sema_post(3synch) is faithfully followed before and after any access of the data.

sema_init(3synch)

sema_init initializes the semaphore sema of type type to protect sema_count resources.

sema_wait(3synch)

sema_wait acquires the semaphore pointed to by sema.

If the semaphore is available (that is, if the semaphore value is greater than zero), sema_wait decrements the semaphore value and returns to the caller.

If the semaphore is unavailable (that is, the semaphore value is zero or less), sema_wait decrements the semaphore value and suspends execution of the calling thread until the semaphore becomes available to the caller.

If a thread waiting on a semaphore is interrupted by a signal, the signal handler will run, but then the thread will resume waiting for the semaphore. Thus, when sema_wait returns without an error, it will always have acquired the semaphore.

sema_trywait(3synch)

sema_trywait makes a single attempt to acquire the semaphore pointed to by sema. If the semaphore is available, sema_trywait decrements the semaphore value and returns to the caller.

If sema_trywait cannot immediately acquire the semaphore, it returns EBUSY to the caller, it does not block the caller to wait for the semaphore or decrement the semaphore value.

sema_post(3synch)

sema_post increments the count of the semaphore pointed to by sema, and if the new count value is less than or equal to zero, makes the next thread waiting at the semaphore runnable.

If more than one thread is waiting, release from the blocked group is scheduling policy-specific for bound threads, and may be dependent on scheduling parameters for multiplexed threads.

sema_destroy(3synch)

sema_destroy destroys the semaphore pointed to by sema. This includes invalidating sema and freeing any associated dynamically allocated resources.

Warnings

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

References

Intro(3synch), sema_destroy(3synch) sema_init(3synch) sema_post(3synch), sema_trywait(3synch), sema_wait(3synch)