Subversion Repositories openrisc_me

@node POSIX Threads

@c @node POSIX Threads, , Top, Top

@chapter POSIX Threads

@c %MENU% The standard threads library

@c This chapter needs more work bigtime. -zw

This chapter describes the pthreads (POSIX threads) library.  This

library provides support functions for multithreaded programs: thread

primitives, synchronization objects, and so forth.  It also implements

POSIX 1003.1b semaphores (not to be confused with System V semaphores).

The threads operations (@samp{pthread_*}) do not use @var{errno}.

Instead they return an error code directly.  The semaphore operations do

use @var{errno}.

@menu

* Basic Thread Operations::     Creating, terminating, and waiting for threads.

* Thread Attributes::           Tuning thread scheduling.

* Cancellation::                Stopping a thread before it's done.

* Cleanup Handlers::            Deallocating resources when a thread is

                                  canceled.

* Mutexes::                     One way to synchronize threads.

* Condition Variables::         Another way.

* POSIX Semaphores::            And a third way.

* Thread-Specific Data::        Variables with different values in

                                  different threads.

* Threads and Signal Handling:: Why you should avoid mixing the two, and

                                  how to do it if you must.

* Threads and Fork::            Interactions between threads and the

                                  @code{fork} function.

* Streams and Fork::            Interactions between stdio streams and

                                  @code{fork}.

* Miscellaneous Thread Functions:: A grab bag of utility routines.

@end menu

@node Basic Thread Operations

@section Basic Thread Operations

These functions are the thread equivalents of @code{fork}, @code{exit},

and @code{wait}.

@comment pthread.h

@comment POSIX

@deftypefun int pthread_create (pthread_t * @var{thread}, pthread_attr_t * @var{attr}, void * (*@var{start_routine})(void *), void * @var{arg})

@code{pthread_create} creates a new thread of control that executes

concurrently with the calling thread. The new thread calls the

function @var{start_routine}, passing it @var{arg} as first argument. The

new thread terminates either explicitly, by calling @code{pthread_exit},

or implicitly, by returning from the @var{start_routine} function. The

latter case is equivalent to calling @code{pthread_exit} with the result

returned by @var{start_routine} as exit code.

The @var{attr} argument specifies thread attributes to be applied to the

new thread. @xref{Thread Attributes}, for details. The @var{attr}

argument can also be @code{NULL}, in which case default attributes are

used: the created thread is joinable (not detached) and has an ordinary

(not realtime) scheduling policy.

On success, the identifier of the newly created thread is stored in the

location pointed by the @var{thread} argument, and a 0 is returned. On

error, a non-zero error code is returned.

This function may return the following errors:

@table @code

@item EAGAIN

Not enough system resources to create a process for the new thread,

or more than @code{PTHREAD_THREADS_MAX} threads are already active.

@end table

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun void pthread_exit (void *@var{retval})

@code{pthread_exit} terminates the execution of the calling thread.  All

cleanup handlers (@pxref{Cleanup Handlers}) that have been set for the

calling thread with @code{pthread_cleanup_push} are executed in reverse

order (the most recently pushed handler is executed first). Finalization

functions for thread-specific data are then called for all keys that

have non-@code{NULL} values associated with them in the calling thread

(@pxref{Thread-Specific Data}).  Finally, execution of the calling

thread is stopped.

The @var{retval} argument is the return value of the thread. It can be

retrieved from another thread using @code{pthread_join}.

The @code{pthread_exit} function never returns.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_cancel (pthread_t @var{thread})

@code{pthread_cancel} sends a cancellation request to the thread denoted

by the @var{thread} argument.  If there is no such thread,

@code{pthread_cancel} fails and returns @code{ESRCH}.  Otherwise it

returns 0. @xref{Cancellation}, for details.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_join (pthread_t @var{th}, void **thread_@var{return})

@code{pthread_join} suspends the execution of the calling thread until

the thread identified by @var{th} terminates, either by calling

@code{pthread_exit} or by being canceled.

If @var{thread_return} is not @code{NULL}, the return value of @var{th}

is stored in the location pointed to by @var{thread_return}.  The return

value of @var{th} is either the argument it gave to @code{pthread_exit},

or @code{PTHREAD_CANCELED} if @var{th} was canceled.

The joined thread @code{th} must be in the joinable state: it must not

have been detached using @code{pthread_detach} or the

@code{PTHREAD_CREATE_DETACHED} attribute to @code{pthread_create}.

When a joinable thread terminates, its memory resources (thread

descriptor and stack) are not deallocated until another thread performs

@code{pthread_join} on it. Therefore, @code{pthread_join} must be called

once for each joinable thread created to avoid memory leaks.

At most one thread can wait for the termination of a given

thread. Calling @code{pthread_join} on a thread @var{th} on which

another thread is already waiting for termination returns an error.

@code{pthread_join} is a cancellation point. If a thread is canceled

while suspended in @code{pthread_join}, the thread execution resumes

immediately and the cancellation is executed without waiting for the

@var{th} thread to terminate. If cancellation occurs during

@code{pthread_join}, the @var{th} thread remains not joined.

On success, the return value of @var{th} is stored in the location

pointed to by @var{thread_return}, and 0 is returned. On error, one of

the following values is returned:

@table @code

@item ESRCH

No thread could be found corresponding to that specified by @var{th}.

@item EINVAL

The @var{th} thread has been detached, or another thread is already

waiting on termination of @var{th}.

@item EDEADLK

The @var{th} argument refers to the calling thread.

@end table

@end deftypefun

@node Thread Attributes

@section Thread Attributes

@comment pthread.h

@comment POSIX

Threads have a number of attributes that may be set at creation time.

This is done by filling a thread attribute object @var{attr} of type

@code{pthread_attr_t}, then passing it as second argument to

@code{pthread_create}. Passing @code{NULL} is equivalent to passing a

thread attribute object with all attributes set to their default values.

Attribute objects are consulted only when creating a new thread.  The

same attribute object can be used for creating several threads.

Modifying an attribute object after a call to @code{pthread_create} does

not change the attributes of the thread previously created.

@comment pthread.h

@comment POSIX

@deftypefun int pthread_attr_init (pthread_attr_t *@var{attr})

@code{pthread_attr_init} initializes the thread attribute object

@var{attr} and fills it with default values for the attributes. (The

default values are listed below for each attribute.)

Each attribute @var{attrname} (see below for a list of all attributes)

can be individually set using the function

@code{pthread_attr_set@var{attrname}} and retrieved using the function

@code{pthread_attr_get@var{attrname}}.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_attr_destroy (pthread_attr_t *@var{attr})

@code{pthread_attr_destroy} destroys the attribute object pointed to by

@var{attr} releasing any resources associated with it.  @var{attr} is

left in an undefined state, and you must not use it again in a call to

any pthreads function until it has been reinitialized.

@end deftypefun

@findex pthread_attr_setdetachstate

@findex pthread_attr_setguardsize

@findex pthread_attr_setinheritsched

@findex pthread_attr_setschedparam

@findex pthread_attr_setschedpolicy

@findex pthread_attr_setscope

@findex pthread_attr_setstack

@findex pthread_attr_setstackaddr

@findex pthread_attr_setstacksize

@comment pthread.h

@comment POSIX

@deftypefun int pthread_attr_setattr (pthread_attr_t *@var{obj}, int @var{value})

Set attribute @var{attr} to @var{value} in the attribute object pointed

to by @var{obj}.  See below for a list of possible attributes and the

values they can take.

On success, these functions return 0.  If @var{value} is not meaningful

for the @var{attr} being modified, they will return the error code

@code{EINVAL}.  Some of the functions have other failure modes; see

below.

@end deftypefun

@findex pthread_attr_getdetachstate

@findex pthread_attr_getguardsize

@findex pthread_attr_getinheritsched

@findex pthread_attr_getschedparam

@findex pthread_attr_getschedpolicy

@findex pthread_attr_getscope

@findex pthread_attr_getstack

@findex pthread_attr_getstackaddr

@findex pthread_attr_getstacksize

@comment pthread.h

@comment POSIX

@deftypefun int pthread_attr_getattr (const pthread_attr_t *@var{obj}, int *@var{value})

Store the current setting of @var{attr} in @var{obj} into the variable

pointed to by @var{value}.

These functions always return 0.

@end deftypefun

The following thread attributes are supported:

@table @samp

@item detachstate

Choose whether the thread is created in the joinable state (value

@code{PTHREAD_CREATE_JOINABLE}) or in the detached state

(@code{PTHREAD_CREATE_DETACHED}).  The default is

@code{PTHREAD_CREATE_JOINABLE}.

In the joinable state, another thread can synchronize on the thread

termination and recover its termination code using @code{pthread_join},

but some of the thread resources are kept allocated after the thread

terminates, and reclaimed only when another thread performs

@code{pthread_join} on that thread.

In the detached state, the thread resources are immediately freed when

it terminates, but @code{pthread_join} cannot be used to synchronize on

the thread termination.

A thread created in the joinable state can later be put in the detached

thread using @code{pthread_detach}.

@item schedpolicy

Select the scheduling policy for the thread: one of @code{SCHED_OTHER}

(regular, non-realtime scheduling), @code{SCHED_RR} (realtime,

round-robin) or @code{SCHED_FIFO} (realtime, first-in first-out).

The default is @code{SCHED_OTHER}.

@c Not doc'd in our manual: FIXME.

@c See @code{sched_setpolicy} for more information on scheduling policies.

The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO}

are available only to processes with superuser privileges.

@code{pthread_attr_setschedparam} will fail and return @code{ENOTSUP} if

you try to set a realtime policy when you are unprivileged.

The scheduling policy of a thread can be changed after creation with

@code{pthread_setschedparam}.

@item schedparam

Change the scheduling parameter (the scheduling priority)

for the thread.  The default is 0.

This attribute is not significant if the scheduling policy is

@code{SCHED_OTHER}; it only matters for the realtime policies

@code{SCHED_RR} and @code{SCHED_FIFO}.

The scheduling priority of a thread can be changed after creation with

@code{pthread_setschedparam}.

@item inheritsched

Choose whether the scheduling policy and scheduling parameter for the

newly created thread are determined by the values of the

@var{schedpolicy} and @var{schedparam} attributes (value

@code{PTHREAD_EXPLICIT_SCHED}) or are inherited from the parent thread

(value @code{PTHREAD_INHERIT_SCHED}).  The default is

@code{PTHREAD_EXPLICIT_SCHED}.

@item scope

Choose the scheduling contention scope for the created thread.  The

default is @code{PTHREAD_SCOPE_SYSTEM}, meaning that the threads contend

for CPU time with all processes running on the machine. In particular,

thread priorities are interpreted relative to the priorities of all

other processes on the machine. The other possibility,

@code{PTHREAD_SCOPE_PROCESS}, means that scheduling contention occurs

only between the threads of the running process: thread priorities are

interpreted relative to the priorities of the other threads of the

process, regardless of the priorities of other processes.

@code{PTHREAD_SCOPE_PROCESS} is not supported in LinuxThreads.  If you

try to set the scope to this value, @code{pthread_attr_setscope} will

fail and return @code{ENOTSUP}.

@item stackaddr

Provide an address for an application managed stack.  The size of the

stack must be at least @code{PTHREAD_STACK_MIN}.

@item stacksize

Change the size of the stack created for the thread.  The value defines

the minimum stack size, in bytes.

If the value exceeds the system's maximum stack size, or is smaller

than @code{PTHREAD_STACK_MIN}, @code{pthread_attr_setstacksize} will

fail and return @code{EINVAL}.

@item stack

Provide both the address and size of an application managed stack to

use for the new thread.  The base of the memory area is @var{stackaddr}

with the size of the memory area, @var{stacksize}, measured in bytes.

If the value of @var{stacksize} is less than @code{PTHREAD_STACK_MIN},

or greater than the system's maximum stack size, or if the value of

@var{stackaddr} lacks the proper alignment, @code{pthread_attr_setstack}

will fail and return @code{EINVAL}.

@item guardsize

Change the minimum size in bytes of the guard area for the thread's

stack.  The default size is a single page.  If this value is set, it

will be rounded up to the nearest page size.  If the value is set to 0,

a guard area will not be created for this thread.  The space allocated

for the guard area is used to catch stack overflow.  Therefore, when

allocating large structures on the stack, a larger guard area may be

required to catch a stack overflow.

If the caller is managing their own stacks (if the @code{stackaddr}

attribute has been set), then the @code{guardsize} attribute is ignored.

If the value exceeds the @code{stacksize}, @code{pthread_atrr_setguardsize}

will fail and return @code{EINVAL}.

@end table

@node Cancellation

@section Cancellation

Cancellation is the mechanism by which a thread can terminate the

execution of another thread. More precisely, a thread can send a

cancellation request to another thread. Depending on its settings, the

target thread can then either ignore the request, honor it immediately,

or defer it till it reaches a cancellation point.  When threads are

first created by @code{pthread_create}, they always defer cancellation

requests.

When a thread eventually honors a cancellation request, it behaves as if

@code{pthread_exit(PTHREAD_CANCELED)} was called.  All cleanup handlers

are executed in reverse order, finalization functions for

thread-specific data are called, and finally the thread stops executing.

If the canceled thread was joinable, the return value

@code{PTHREAD_CANCELED} is provided to whichever thread calls

@var{pthread_join} on it. See @code{pthread_exit} for more information.

Cancellation points are the points where the thread checks for pending

cancellation requests and performs them.  The POSIX threads functions

@code{pthread_join}, @code{pthread_cond_wait},

@code{pthread_cond_timedwait}, @code{pthread_testcancel},

@code{sem_wait}, and @code{sigwait} are cancellation points.  In

addition, these system calls are cancellation points:

@multitable @columnfractions .33 .33 .33

@item @t{accept}        @tab @t{open}           @tab @t{sendmsg}

@item @t{close}         @tab @t{pause}          @tab @t{sendto}

@item @t{connect}       @tab @t{read}           @tab @t{system}

@item @t{fcntl}         @tab @t{recv}           @tab @t{tcdrain}

@item @t{fsync}         @tab @t{recvfrom}       @tab @t{wait}

@item @t{lseek}         @tab @t{recvmsg}        @tab @t{waitpid}

@item @t{msync}         @tab @t{send}           @tab @t{write}

@item @t{nanosleep}

@end multitable

@noindent

All library functions that call these functions (such as

@code{printf}) are also cancellation points.

@comment pthread.h

@comment POSIX

@deftypefun int pthread_setcancelstate (int @var{state}, int *@var{oldstate})

@code{pthread_setcancelstate} changes the cancellation state for the

calling thread -- that is, whether cancellation requests are ignored or

not. The @var{state} argument is the new cancellation state: either

@code{PTHREAD_CANCEL_ENABLE} to enable cancellation, or

@code{PTHREAD_CANCEL_DISABLE} to disable cancellation (cancellation

requests are ignored).

If @var{oldstate} is not @code{NULL}, the previous cancellation state is

stored in the location pointed to by @var{oldstate}, and can thus be

restored later by another call to @code{pthread_setcancelstate}.

If the @var{state} argument is not @code{PTHREAD_CANCEL_ENABLE} or

@code{PTHREAD_CANCEL_DISABLE}, @code{pthread_setcancelstate} fails and

returns @code{EINVAL}.  Otherwise it returns 0.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_setcanceltype (int @var{type}, int *@var{oldtype})

@code{pthread_setcanceltype} changes the type of responses to

cancellation requests for the calling thread: asynchronous (immediate)

or deferred.  The @var{type} argument is the new cancellation type:

either @code{PTHREAD_CANCEL_ASYNCHRONOUS} to cancel the calling thread

as soon as the cancellation request is received, or

@code{PTHREAD_CANCEL_DEFERRED} to keep the cancellation request pending

until the next cancellation point. If @var{oldtype} is not @code{NULL},

the previous cancellation state is stored in the location pointed to by

@var{oldtype}, and can thus be restored later by another call to

@code{pthread_setcanceltype}.

If the @var{type} argument is not @code{PTHREAD_CANCEL_DEFERRED} or

@code{PTHREAD_CANCEL_ASYNCHRONOUS}, @code{pthread_setcanceltype} fails

and returns @code{EINVAL}.  Otherwise it returns 0.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun void pthread_testcancel (@var{void})

@code{pthread_testcancel} does nothing except testing for pending

cancellation and executing it. Its purpose is to introduce explicit

checks for cancellation in long sequences of code that do not call

cancellation point functions otherwise.

@end deftypefun

@node Cleanup Handlers

@section Cleanup Handlers

Cleanup handlers are functions that get called when a thread terminates,

either by calling @code{pthread_exit} or because of

cancellation. Cleanup handlers are installed and removed following a

stack-like discipline.

The purpose of cleanup handlers is to free the resources that a thread

may hold at the time it terminates. In particular, if a thread exits or

is canceled while it owns a locked mutex, the mutex will remain locked

forever and prevent other threads from executing normally. The best way

to avoid this is, just before locking the mutex, to install a cleanup

handler whose effect is to unlock the mutex. Cleanup handlers can be

used similarly to free blocks allocated with @code{malloc} or close file

descriptors on thread termination.

Here is how to lock a mutex @var{mut} in such a way that it will be

unlocked if the thread is canceled while @var{mut} is locked:

@smallexample

pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);

pthread_mutex_lock(&mut);

/* do some work */

pthread_mutex_unlock(&mut);

pthread_cleanup_pop(0);

@end smallexample

Equivalently, the last two lines can be replaced by

@smallexample

pthread_cleanup_pop(1);

@end smallexample

Notice that the code above is safe only in deferred cancellation mode

(see @code{pthread_setcanceltype}). In asynchronous cancellation mode, a

cancellation can occur between @code{pthread_cleanup_push} and

@code{pthread_mutex_lock}, or between @code{pthread_mutex_unlock} and

@code{pthread_cleanup_pop}, resulting in both cases in the thread trying

to unlock a mutex not locked by the current thread. This is the main

reason why asynchronous cancellation is difficult to use.

If the code above must also work in asynchronous cancellation mode,

then it must switch to deferred mode for locking and unlocking the

mutex:

@smallexample

pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);

pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);

pthread_mutex_lock(&mut);

/* do some work */

pthread_cleanup_pop(1);

pthread_setcanceltype(oldtype, NULL);

@end smallexample

The code above can be rewritten in a more compact and efficient way,

using the non-portable functions @code{pthread_cleanup_push_defer_np}

and @code{pthread_cleanup_pop_restore_np}:

@smallexample

pthread_cleanup_push_defer_np(pthread_mutex_unlock, (void *) &mut);

pthread_mutex_lock(&mut);

/* do some work */

pthread_cleanup_pop_restore_np(1);

@end smallexample

@comment pthread.h

@comment POSIX

@deftypefun void pthread_cleanup_push (void (*@var{routine}) (void *), void *@var{arg})

@code{pthread_cleanup_push} installs the @var{routine} function with

argument @var{arg} as a cleanup handler. From this point on to the

matching @code{pthread_cleanup_pop}, the function @var{routine} will be

called with arguments @var{arg} when the thread terminates, either

through @code{pthread_exit} or by cancellation. If several cleanup

handlers are active at that point, they are called in LIFO order: the

most recently installed handler is called first.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun void pthread_cleanup_pop (int @var{execute})

@code{pthread_cleanup_pop} removes the most recently installed cleanup

handler. If the @var{execute} argument is not 0, it also executes the

handler, by calling the @var{routine} function with arguments

@var{arg}. If the @var{execute} argument is 0, the handler is only

removed but not executed.

@end deftypefun

Matching pairs of @code{pthread_cleanup_push} and

@code{pthread_cleanup_pop} must occur in the same function, at the same

level of block nesting.  Actually, @code{pthread_cleanup_push} and

@code{pthread_cleanup_pop} are macros, and the expansion of

@code{pthread_cleanup_push} introduces an open brace @code{@{} with the

matching closing brace @code{@}} being introduced by the expansion of the

matching @code{pthread_cleanup_pop}.

@comment pthread.h

@comment GNU

@deftypefun void pthread_cleanup_push_defer_np (void (*@var{routine}) (void *), void *@var{arg})

@code{pthread_cleanup_push_defer_np} is a non-portable extension that

combines @code{pthread_cleanup_push} and @code{pthread_setcanceltype}.

It pushes a cleanup handler just as @code{pthread_cleanup_push} does,

but also saves the current cancellation type and sets it to deferred

cancellation. This ensures that the cleanup mechanism is effective even

if the thread was initially in asynchronous cancellation mode.

@end deftypefun

@comment pthread.h

@comment GNU

@deftypefun void pthread_cleanup_pop_restore_np (int @var{execute})

@code{pthread_cleanup_pop_restore_np} pops a cleanup handler introduced

by @code{pthread_cleanup_push_defer_np}, and restores the cancellation

type to its value at the time @code{pthread_cleanup_push_defer_np} was

called.

@end deftypefun

@code{pthread_cleanup_push_defer_np} and

@code{pthread_cleanup_pop_restore_np} must occur in matching pairs, at

the same level of block nesting.

The sequence

@smallexample

pthread_cleanup_push_defer_np(routine, arg);

...

pthread_cleanup_pop_defer_np(execute);

@end smallexample

@noindent

is functionally equivalent to (but more compact and efficient than)

@smallexample

@{

  int oldtype;

  pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);

  pthread_cleanup_push(routine, arg);

  ...

  pthread_cleanup_pop(execute);

  pthread_setcanceltype(oldtype, NULL);

@}

@end smallexample

@node Mutexes

@section Mutexes

A mutex is a MUTual EXclusion device, and is useful for protecting

shared data structures from concurrent modifications, and implementing

critical sections and monitors.

A mutex has two possible states: unlocked (not owned by any thread),

and locked (owned by one thread). A mutex can never be owned by two

different threads simultaneously. A thread attempting to lock a mutex

that is already locked by another thread is suspended until the owning

thread unlocks the mutex first.

None of the mutex functions is a cancellation point, not even

@code{pthread_mutex_lock}, in spite of the fact that it can suspend a

thread for arbitrary durations. This way, the status of mutexes at

cancellation points is predictable, allowing cancellation handlers to

unlock precisely those mutexes that need to be unlocked before the

thread stops executing. Consequently, threads using deferred

cancellation should never hold a mutex for extended periods of time.

It is not safe to call mutex functions from a signal handler.  In

particular, calling @code{pthread_mutex_lock} or

@code{pthread_mutex_unlock} from a signal handler may deadlock the

calling thread.

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr})

@code{pthread_mutex_init} initializes the mutex object pointed to by

@var{mutex} according to the mutex attributes specified in @var{mutexattr}.

If @var{mutexattr} is @code{NULL}, default attributes are used instead.

The LinuxThreads implementation supports only one mutex attribute,

the @var{mutex type}, which is either ``fast'', ``recursive'', or

``error checking''. The type of a mutex determines whether

it can be locked again by a thread that already owns it.

The default type is ``fast''.

Variables of type @code{pthread_mutex_t} can also be initialized

statically, using the constants @code{PTHREAD_MUTEX_INITIALIZER} (for

timed mutexes), @code{PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP} (for

recursive mutexes), @code{PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP}

(for fast mutexes(, and @code{PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP}

(for error checking mutexes).

@code{pthread_mutex_init} always returns 0.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutex_lock (pthread_mutex_t *mutex))

@code{pthread_mutex_lock} locks the given mutex. If the mutex is

currently unlocked, it becomes locked and owned by the calling thread,

and @code{pthread_mutex_lock} returns immediately. If the mutex is

already locked by another thread, @code{pthread_mutex_lock} suspends the

calling thread until the mutex is unlocked.

If the mutex is already locked by the calling thread, the behavior of

@code{pthread_mutex_lock} depends on the type of the mutex. If the mutex

is of the ``fast'' type, the calling thread is suspended.  It will

remain suspended forever, because no other thread can unlock the mutex.

If  the mutex is of the ``error checking'' type, @code{pthread_mutex_lock}

returns immediately with the error code @code{EDEADLK}.  If the mutex is

of the ``recursive'' type, @code{pthread_mutex_lock} succeeds and

returns immediately, recording the number of times the calling thread

has locked the mutex. An equal number of @code{pthread_mutex_unlock}

operations must be performed before the mutex returns to the unlocked

state.

@c This doesn't discuss PTHREAD_MUTEX_TIMED_NP mutex attributes. FIXME

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex})

@code{pthread_mutex_trylock} behaves identically to

@code{pthread_mutex_lock}, except that it does not block the calling

thread if the mutex is already locked by another thread (or by the

calling thread in the case of a ``fast'' mutex). Instead,

@code{pthread_mutex_trylock} returns immediately with the error code

@code{EBUSY}.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutex_timedlock (pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime})

The @code{pthread_mutex_timedlock} is similar to the

@code{pthread_mutex_lock} function but instead of blocking for in

indefinite time if the mutex is locked by another thread, it returns

when the time specified in @var{abstime} is reached.

This function can only be used on standard (``timed'') and ``error

checking'' mutexes.  It behaves just like @code{pthread_mutex_lock} for

all other types.

If the mutex is successfully locked, the function returns zero.  If the

time specified in @var{abstime} is reached without the mutex being locked,

@code{ETIMEDOUT} is returned.

This function was introduced in the POSIX.1d revision of the POSIX standard.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex})

@code{pthread_mutex_unlock} unlocks the given mutex. The mutex is

assumed to be locked and owned by the calling thread on entrance to

@code{pthread_mutex_unlock}. If the mutex is of the ``fast'' type,

@code{pthread_mutex_unlock} always returns it to the unlocked state. If

it is of the ``recursive'' type, it decrements the locking count of the

mutex (number of @code{pthread_mutex_lock} operations performed on it by

the calling thread), and only when this count reaches zero is the mutex

actually unlocked.

On ``error checking'' mutexes, @code{pthread_mutex_unlock} actually

checks at run-time that the mutex is locked on entrance, and that it was

locked by the same thread that is now calling

@code{pthread_mutex_unlock}.  If these conditions are not met,

@code{pthread_mutex_unlock} returns @code{EPERM}, and the mutex remains

unchanged.  ``Fast'' and ``recursive'' mutexes perform no such checks,

thus allowing a locked mutex to be unlocked by a thread other than its

owner. This is non-portable behavior and must not be relied upon.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex})

@code{pthread_mutex_destroy} destroys a mutex object, freeing the

resources it might hold. The mutex must be unlocked on entrance. In the

LinuxThreads implementation, no resources are associated with mutex

objects, thus @code{pthread_mutex_destroy} actually does nothing except

checking that the mutex is unlocked.

If the mutex is locked by some thread, @code{pthread_mutex_destroy}

returns @code{EBUSY}.  Otherwise it returns 0.

@end deftypefun

If any of the above functions (except @code{pthread_mutex_init})

is applied to an uninitialized mutex, they will simply return

@code{EINVAL} and do nothing.

A shared global variable @var{x} can be protected by a mutex as follows:

@smallexample

int x;

pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

@end smallexample

All accesses and modifications to @var{x} should be bracketed by calls to

@code{pthread_mutex_lock} and @code{pthread_mutex_unlock} as follows:

@smallexample

pthread_mutex_lock(&mut);

/* operate on x */

pthread_mutex_unlock(&mut);

@end smallexample

Mutex attributes can be specified at mutex creation time, by passing a

mutex attribute object as second argument to @code{pthread_mutex_init}.

Passing @code{NULL} is equivalent to passing a mutex attribute object

with all attributes set to their default values.

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutexattr_init (pthread_mutexattr_t *@var{attr})

@code{pthread_mutexattr_init} initializes the mutex attribute object

@var{attr} and fills it with default values for the attributes.

This function always returns 0.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr})

@code{pthread_mutexattr_destroy} destroys a mutex attribute object,

which must not be reused until it is

reinitialized. @code{pthread_mutexattr_destroy} does nothing in the

LinuxThreads implementation.

This function always returns 0.

@end deftypefun

LinuxThreads supports only one mutex attribute: the mutex type, which is

either @code{PTHREAD_MUTEX_ADAPTIVE_NP} for ``fast'' mutexes,

@code{PTHREAD_MUTEX_RECURSIVE_NP} for ``recursive'' mutexes,

@code{PTHREAD_MUTEX_TIMED_NP} for ``timed'' mutexes, or

@code{PTHREAD_MUTEX_ERRORCHECK_NP} for ``error checking'' mutexes.  As

the @code{NP} suffix indicates, this is a non-portable extension to the

POSIX standard and should not be employed in portable programs.

The mutex type determines what happens if a thread attempts to lock a

mutex it already owns with @code{pthread_mutex_lock}. If the mutex is of

the ``fast'' type, @code{pthread_mutex_lock} simply suspends the calling

thread forever.  If the mutex is of the ``error checking'' type,

@code{pthread_mutex_lock} returns immediately with the error code

@code{EDEADLK}.  If the mutex is of the ``recursive'' type, the call to

@code{pthread_mutex_lock} returns immediately with a success return

code. The number of times the thread owning the mutex has locked it is

recorded in the mutex. The owning thread must call

@code{pthread_mutex_unlock} the same number of times before the mutex

returns to the unlocked state.

The default mutex type is ``timed'', that is, @code{PTHREAD_MUTEX_TIMED_NP}.

@c This doesn't describe how a ``timed'' mutex behaves. FIXME

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutexattr_settype (pthread_mutexattr_t *@var{attr}, int @var{type})

@code{pthread_mutexattr_settype} sets the mutex type attribute in

@var{attr} to the value specified by @var{type}.

If @var{type} is not @code{PTHREAD_MUTEX_ADAPTIVE_NP},

@code{PTHREAD_MUTEX_RECURSIVE_NP}, @code{PTHREAD_MUTEX_TIMED_NP}, or

@code{PTHREAD_MUTEX_ERRORCHECK_NP}, this function will return

@code{EINVAL} and leave @var{attr} unchanged.

The standard Unix98 identifiers @code{PTHREAD_MUTEX_DEFAULT},

@code{PTHREAD_MUTEX_NORMAL}, @code{PTHREAD_MUTEX_RECURSIVE},

and @code{PTHREAD_MUTEX_ERRORCHECK} are also permitted.

@end deftypefun

@comment pthread.h

@comment POSIX

@deftypefun int pthread_mutexattr_gettype (const pthread_mutexattr_t *@var{attr}, int *@var{type})

@code{pthread_mutexattr_gettype} retrieves the current value of the

mutex type attribute in @var{attr} and stores it in the location pointed

to by @var{type}.

This function always returns 0.

@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 canceled 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);