Tribblix: manual page: sem

SEM_WAIT(3C) Standard C Library Functions SEM_WAIT(3C)

NAME

sem_wait, sem_trywait - acquire or wait for a semaphore

SYNOPSIS

#include <semaphore.h>

int sem_wait(sem_t *sem);

int sem_trywait(sem_t *sem);

DESCRIPTION

The sem_wait() function locks the semaphore referenced by sem by
performing a semaphore lock operation on that semaphore. If the
semaphore value is currently zero, then the calling thread will not
return from the call to sem_wait() until it either locks the
semaphore or the call is interrupted by a signal. The sem_trywait()
function locks the semaphore referenced by sem only if the semaphore
is currently not locked; that is, if the semaphore value is currently
positive. Otherwise, it does not lock the semaphore.

Upon successful return, the state of the semaphore is locked and
remains locked until the sem_post(3C) function is executed and
returns successfully.

The sem_wait() function is interruptible by the delivery of a signal.

RETURN VALUES

The sem_wait() and sem_trywait() functions return 0 if the calling
process successfully performed the semaphore lock operation on the
semaphore designated by sem. If the call was unsuccessful, the state
of the semaphore is unchanged, and the function returns -1 and sets
errno to indicate the error.

ERRORS

The sem_wait() and sem_trywait() functions will fail if:

EINVAL
The sem function does not refer to a valid semaphore.

ENOSYS
The sem_wait() and sem_trywait() functions are not
supported by the system.

The sem_trywait() function will fail if:

EAGAIN
The semaphore was already locked, so it cannot be
immediately locked by the sem_trywait() operation.

The sem_wait() and sem_trywait() functions may fail if:

EDEADLK
A deadlock condition was detected; that is, two separate
processes are waiting for an available resource to be
released via a semaphore "held" by the other process.

EINTR
A signal interrupted this function.

USAGE

Realtime applications may encounter priority inversion when using
semaphores. The problem occurs when a high priority thread "locks"
(that is, waits on) a semaphore that is about to be "unlocked" (that
is, posted) by a low priority thread, but the low priority thread is
preempted by a medium priority thread. This scenario leads to
priority inversion; a high priority thread is blocked by lower
priority threads for an unlimited period of time. During system
design, realtime programmers must take into account the possibility
of this kind of priority inversion. They can deal with it in a number
of ways, such as by having critical sections that are guarded by
semaphores execute at a high priority, so that a thread cannot be
preempted while executing in its critical section.

EXAMPLES

Example 1: The customer waiting-line in a bank may be analogous to the

synchronization scheme of a semaphore utilizing sem_wait() and
sem_trywait():

#include <errno.h>
#define TELLERS 10
sem_t bank_line; /* semaphore */
int banking_hours(), deposit_withdrawal;
void *customer(), do_business(), skip_banking_today();
thread_t tid;
...

sem_init(&bank_line,TRUE,TELLERS); /* 10 tellers
available */
while(banking_hours())
thr_create(NULL, NULL, customer,
(void *)deposit_withdrawal, THREAD_NEW_LWP, &tid);
...

void *
customer(deposit_withdrawal)
void *deposit_withdrawal;
{
int this_customer, in_a_hurry = 50;
this_customer = rand() % 100;
if (this_customer == in_a_hurry) {
if (sem_trywait(&bank_line) != 0)
if (errno == EAGAIN) { /* no teller available */
skip_banking_today(this_customer);
return;
} /*else go immediately to available teller
& decrement bank_line*/
}
else
sem_wait(&bank_line); /* wait for next teller,
then proceed, and decrement bank_line */
do_business((int *)deposit_withdrawal);
sem_getvalue(&bank_line,&num_tellers);
sem_post(&bank_line); /* increment bank_line;
this_customer's teller is now available */
}

ATTRIBUTES