linuxthreads.texi

用于嵌入式Linux系统的标准C的库函数

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.

@code{pthread_key_create} returns 0 unless @code{PTHREAD_KEYS_MAX} keys
have already been allocated, in which case it fails and returns
@code{EAGAIN}.
@end deftypefun


@comment pthread.h
@comment POSIX
@deftypefun int pthread_key_delete (pthread_key_t @var{key})
@code{pthread_key_delete} deallocates a TSD key. It does not check
whether non-@code{NULL} values are associated with that key in the
currently executing threads, nor call the destructor function associated
with the key.

If there is no such key @var{key}, it returns @code{EINVAL}.  Otherwise
it returns 0.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{pointer})
@code{pthread_setspecific} changes the value associated with @var{key}
in the calling thread, storing the given @var{pointer} instead.

If there is no such key @var{key}, it returns @code{EINVAL}.  Otherwise
it returns 0.
@end deftypefun

@comment pthread.h
@comment POSIX
@deftypefun {void *} pthread_getspecific (pthread_key_t @var{key})
@code{pthread_getspecific} returns the value currently associated with
@var{key} in the calling thread.

If there is no such key @var{key}, it returns @code{NULL}.
@end deftypefun

The following code fragment allocates a thread-specific array of 100
characters, with automatic reclaimation at thread exit:

@smallexample
/* Key for the thread-specific buffer */
static pthread_key_t buffer_key;

/* Once-only initialisation of the key */
static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;

/* Allocate the thread-specific buffer */
void buffer_alloc(void)
@{
  pthread_once(&buffer_key_once, buffer_key_alloc);
  pthread_setspecific(buffer_key, malloc(100));
@}

/* Return the thread-specific buffer */
char * get_buffer(void)
@{
  return (char *) pthread_getspecific(buffer_key);
@}

/* Allocate the key */
static void buffer_key_alloc()
@{
  pthread_key_create(&buffer_key, buffer_destroy);
@}

/* Free the thread-specific buffer */
static void buffer_destroy(void * buf)
@{
  free(buf);
@}
@end smallexample

@node Threads and Signal Handling
@section Threads and Signal Handling

@comment pthread.h
@comment POSIX
@deftypefun int pthread_sigmask (int @var{how}, const sigset_t *@var{newmask}, sigset_t *@var{oldmask})
@code{pthread_sigmask} changes the signal mask for the calling thread as
described by the @var{how} and @var{newmask} arguments. If @var{oldmask}
is not @code{NULL}, the previous signal mask is stored in the location
pointed to by @var{oldmask}.

The meaning of the @var{how} and @var{newmask} arguments is the same as
for @code{sigprocmask}. If @var{how} is @code{SIG_SETMASK}, the signal