linuxthreads.texi

Axis 221 camera embedded programing interface

@end deftypefun

@node Condition Variables
@section Condition Variables

A condition (short for ``condition variable'') is a synchronization
device that allows threads to suspend execution until some predicate on
shared data is satisfied. The basic operations on conditions are: signal
the condition (when the predicate becomes true), and wait for the
condition, suspending the thread execution until another thread signals
the condition.

A condition variable must always be associated with a mutex, to avoid
the race condition where a thread prepares to wait on a condition
variable and another thread signals the condition just before the first
thread actually waits on it.

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cond_init (pthread_cond_t *@var{cond}, pthread_condattr_t *cond_@var{attr})

@code{pthread_cond_init} initializes the condition variable @var{cond},
using the condition attributes specified in @var{cond_attr}, or default
attributes if @var{cond_attr} is @code{NULL}. The LinuxThreads
implementation supports no attributes for conditions, hence the
@var{cond_attr} parameter is actually ignored.

Variables of type @code{pthread_cond_t} can also be initialized
statically, using the constant @code{PTHREAD_COND_INITIALIZER}.

This function always returns 0.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cond_signal (pthread_cond_t *@var{cond})
@code{pthread_cond_signal} restarts one of the threads that are waiting
on the condition variable @var{cond}. If no threads are waiting on
@var{cond}, nothing happens. If several threads are waiting on
@var{cond}, exactly one is restarted, but it is not specified which.

This function always returns 0.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cond_broadcast (pthread_cond_t *@var{cond})
@code{pthread_cond_broadcast} restarts all the threads that are waiting
on the condition variable @var{cond}. Nothing happens if no threads are
waiting on @var{cond}.

This function always returns 0.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cond_wait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex})
@code{pthread_cond_wait} atomically unlocks the @var{mutex} (as per
@code{pthread_unlock_mutex}) and waits for the condition variable
@var{cond} to be signaled. The thread execution is suspended and does
not consume any CPU time until the condition variable is signaled. The
@var{mutex} must be locked by the calling thread on entrance to
@code{pthread_cond_wait}. Before returning to the calling thread,
@code{pthread_cond_wait} re-acquires @var{mutex} (as per
@code{pthread_lock_mutex}).

Unlocking the mutex and suspending on the condition variable is done
atomically. Thus, if all threads always acquire the mutex before
signaling the condition, this guarantees that the condition cannot be
signaled (and thus ignored) between the time a thread locks the mutex
and the time it waits on the condition variable.

This function always returns 0.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cond_timedwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})
@code{pthread_cond_timedwait} atomically unlocks @var{mutex} and waits
on @var{cond}, as @code{pthread_cond_wait} does, but it also bounds the
duration of the wait. If @var{cond} has not been signaled before time
@var{abstime}, the mutex @var{mutex} is re-acquired and
@code{pthread_cond_timedwait} returns the error code @code{ETIMEDOUT}.
The wait can also be interrupted by a signal; in that case
@code{pthread_cond_timedwait} returns @code{EINTR}.

The @var{abstime} parameter specifies an absolute time, with the same
origin as @code{time} and @code{gettimeofday}: an @var{abstime} of 0
corresponds to 00:00:00 GMT, January 1, 1970.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_cond_destroy (pthread_cond_t *@var{cond})
@code{pthread_cond_destroy} destroys the condition variable @var{cond},
freeing the resources it might hold.  If any threads are waiting on the
condition variable, @code{pthread_cond_destroy} leaves @var{cond}
untouched and returns @code{EBUSY}.  Otherwise it returns 0, and
@var{cond} must not be used again until it is reinitialized.

In the LinuxThreads implementation, no resources are associated with
condition variables, so @code{pthread_cond_destroy} actually does
nothing.
@end deftypefun

@code{pthread_cond_wait} and @code{pthread_cond_timedwait} are
cancellation points. If a thread is cancelled while suspended in one of
these functions, the thread immediately resumes execution, relocks the
mutex specified by  @var{mutex}, and finally executes the cancellation.
Consequently, cleanup handlers are assured that @var{mutex} is locked
when they are called.

It is not safe to call the condition variable functions from a signal
handler. In particular, calling @code{pthread_cond_signal} or
@code{pthread_cond_broadcast} from a signal handler may deadlock the
calling thread.

Consider two shared variables @var{x} and @var{y}, protected by the
mutex @var{mut}, and a condition variable @var{cond} that is to be
signaled whenever @var{x} becomes greater than @var{y}.

@smallexample
int x,y;
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
@end smallexample

Waiting until @var{x} is greater than @var{y} is performed as follows:

@smallexample
pthread_mutex_lock(&mut);
while (x <= y) @{
        pthread_cond_wait(&cond, &mut);
@}
/* operate on x and y */
pthread_mutex_unlock(&mut);
@end smallexample

Modifications on @var{x} and @var{y} that may cause @var{x} to become greater than
@var{y} should signal the condition if needed:

@smallexample
pthread_mutex_lock(&mut);
/* modify x and y */
if (x > y) pthread_cond_broadcast(&cond);
pthread_mutex_unlock(&mut);
@end smallexample

If it can be proved that at most one waiting thread needs to be waken
up (for instance, if there are only two threads communicating through
@var{x} and @var{y}), @code{pthread_cond_signal} can be used as a slightly more
efficient alternative to @code{pthread_cond_broadcast}. In doubt, use
@code{pthread_cond_broadcast}.

To wait for @var{x} to becomes greater than @var{y} with a timeout of 5
seconds, do:

@smallexample
struct timeval now;
struct timespec timeout;
int retcode;

pthread_mutex_lock(&mut);
gettimeofday(&now);
timeout.tv_sec = now.tv_sec + 5;
timeout.tv_nsec = now.tv_usec * 1000;
retcode = 0;
while (x <= y && retcode != ETIMEDOUT) @{
        retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
@}
if (retcode == ETIMEDOUT) @{
        /* timeout occurred */
@} else @{
        /* operate on x and y */
@}
pthread_mutex_unlock(&mut);
@end smallexample

Condition attributes can be specified at condition creation time, by
passing a condition attribute object as second argument to
@code{pthread_cond_init}.  Passing @code{NULL} is equivalent to passing
a condition attribute object with all attributes set to their default
values.

The LinuxThreads implementation supports no attributes for
conditions. The functions on condition attributes are included only for
compliance with the POSIX standard.

@comment pthread.h
@comment POSIX
@deftypefun int pthread_condattr_init (pthread_condattr_t *@var{attr})
@deftypefunx int pthread_condattr_destroy (pthread_condattr_t *@var{attr})
@code{pthread_condattr_init} initializes the condition attribute object
@var{attr} and fills it with default values for the attributes.
@code{pthread_condattr_destroy} destroys the condition attribute object
@var{attr}.

Both functions do nothing in the LinuxThreads implementation.

@code{pthread_condattr_init} and @code{pthread_condattr_destroy} always
return 0.
@end deftypefun

@node POSIX Semaphores
@section POSIX Semaphores

@vindex SEM_VALUE_MAX
Semaphores are counters for resources shared between threads. The
basic operations on semaphores are: increment the counter atomically,
and wait until the counter is non-null and decrement it atomically.

Semaphores have a maximum value past which they cannot be incremented.
The macro @code{SEM_VALUE_MAX} is defined to be this maximum value.  In
the GNU C library, @code{SEM_VALUE_MAX} is equal to @code{INT_MAX}
(@pxref{Range of Type}), but it may be much smaller on other systems.

The pthreads library implements POSIX 1003.1b semaphores.  These should
not be confused with System V semaphores (@code{ipc}, @code{semctl} and
@code{semop}).
@c !!! SysV IPC is not doc'd at all in our manual

All the semaphore functions and macros are defined in @file{semaphore.h}.

@comment semaphore.h
@comment POSIX
@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value})
@code{sem_init} initializes the semaphore object pointed to by
@var{sem}. The count associated with the semaphore is set initially to
@var{value}. The @var{pshared} argument indicates whether the semaphore
is local to the current process (@var{pshared} is zero) or is to be
shared between several processes (@var{pshared} is not zero).

On success @code{sem_init} returns 0.  On failure it returns -1 and sets
@var{errno} to one of the following values:

@table @code
@item EINVAL
@var{value} exceeds the maximal counter value @code{SEM_VALUE_MAX}

@item ENOSYS
@var{pshared} is not zero.  LinuxThreads currently does not support
process-shared semaphores.  (This will eventually change.)
@end table
@end deftypefun

@comment semaphore.h
@comment POSIX
@deftypefun int sem_destroy (sem_t * @var{sem})
@code{sem_destroy} destroys a semaphore object, freeing the resources it
might hold.  If any threads are waiting on the semaphore when
@code{sem_destroy} is called, it fails and sets @var{errno} to
@code{EBUSY}.

In the LinuxThreads implementation, no resources are associated with
semaphore objects, thus @code{sem_destroy} actually does nothing except
checking that no thread is waiting on the semaphore.  This will change
when process-shared semaphores are implemented.
@end deftypefun

@comment semaphore.h
@comment POSIX
@deftypefun int sem_wait (sem_t * @var{sem})
@code{sem_wait} suspends the calling thread until the semaphore pointed
to by @var{sem} has non-zero count. It then atomically decreases the
semaphore count.

@code{sem_wait} is a cancellation point.  It always returns 0.
@end deftypefun

@comment semaphore.h
@comment POSIX
@deftypefun int sem_trywait (sem_t * @var{sem})
@code{sem_trywait} is a non-blocking variant of @code{sem_wait}. If the
semaphore pointed to by @var{sem} has non-zero count, the count is
atomically decreased and @code{sem_trywait} immediately returns 0.  If
the semaphore count is zero, @code{sem_trywait} immediately returns -1
and sets errno to @code{EAGAIN}.
@end deftypefun

@comment semaphore.h
@comment POSIX
@deftypefun int sem_post (sem_t * @var{sem})
@code{sem_post} atomically increases the count of the semaphore pointed to
by @var{sem}. This function never blocks.

@c !!! This para appears not to agree with the code.
On processors supporting atomic compare-and-swap (Intel 486, Pentium and
later, Alpha, PowerPC, MIPS II, Motorola 68k, Ultrasparc), the
@code{sem_post} function is can safely be called from signal handlers.
This is the only thread synchronization function provided by POSIX
threads that is async-signal safe.  On the Intel 386 and earlier Sparc
chips, the current LinuxThreads implementation of @code{sem_post} is not
async-signal safe, because the hardware does not support the required
atomic operations.

@code{sem_post} always succeeds and returns 0, unless the semaphore
count would exceed @code{SEM_VALUE_MAX} after being incremented.  In
that case @code{sem_post} returns -1 and sets @var{errno} to
@code{EINVAL}.  The semaphore count is left unchanged.
@end deftypefun

@comment semaphore.h
@comment POSIX
@deftypefun int sem_getvalue (sem_t * @var{sem}, int * @var{sval})
@code{sem_getvalue} stores in the location pointed to by @var{sval} the
current count of the semaphore @var{sem}.  It always returns 0.
@end deftypefun

@node Thread-Specific Data
@section Thread-Specific Data

Programs often need global or static variables that have different
values in different threads. Since threads share one memory space, this
cannot be achieved with regular variables. Thread-specific data is the
POSIX threads answer to this need.

Each thread possesses a private memory block, the thread-specific data
area, or TSD area for short. This area is indexed by TSD keys. The TSD
area associates values of type @code{void *} to TSD keys. TSD keys are
common to all threads, but the value associated with a given TSD key can
be different in each thread.

For concreteness, the TSD areas can be viewed as arrays of @code{void *}
pointers, TSD keys as integer indices into these arrays, and the value
of a TSD key as the value of the corresponding array element in the
calling thread.

When a thread is created, its TSD area initially associates @code{NULL}
with all keys.

@comment pthread.h
@comment POSIX
@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*destr_function) (void *))
@code{pthread_key_create} allocates a new TSD key. The key is stored in
the location pointed to by @var{key}. There is a limit of
@code{PTHREAD_KEYS_MAX} on the number of keys allocated at a given
time. The value initially associated with the returned key is
@code{NULL} in all currently executing threads.

The @var{destr_function} argument, if not @code{NULL}, specifies a
destructor function associated with the key. When a thread terminates
via @code{pthread_exit} or by cancellation, @var{destr_function} is
called on the value associated with the key in that thread. The
@var{destr_function} is not called if a key is deleted with
@code{pthread_key_delete} or a value is changed with
@code{pthread_setspecific}.  The order in which destructor functions are
called at thread termination time is unspecified.

Before the destructor function is called, the @code{NULL} value is
associated with the key in the current thread.  A destructor function
might, however, re-associate non-@code{NULL} values to that key or some
other key.  To deal with this, if after all the destructors have been
called for all non-@code{NULL} values, there are still some
non-@code{NULL} values with associated destructors, then the process is
repeated.  The LinuxThreads implementation stops the process after
@code{PTHREAD_DESTRUCTOR_ITERATIONS} iterations, even if some
non-@code{NULL} values with associated descriptors remain.  Other
implementations may loop indefinitely.