semaphore(SYNCH)
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(SYNCH)
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(SYNCH)
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(SYNCH),
sema_destroy(SYNCH)
sema_init(SYNCH)
sema_post(SYNCH),
sema_trywait(SYNCH),
sema_wait(SYNCH)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005