glibc/linuxthreads/man/pthread_cond_init.man
Ulrich Drepper 5afdca0087 LinuxThreads library.
1998-03-11 00:42  Wolfram Gloger  <wmglo@dent.med.uni-muenchen.de>
	* linuxthreads/manager.c: Enable resetting of the thread
	scheduling policy to SCHED_OTHER when the parent thread
	has a different one.
1998-02-01 13:51  Ulrich Drepper  <drepper@cygnus.com>
	* sysdeps/unix/sysv/linux/bits/posix_opt.h: Define
	_POSIX_ASYNCHRONOUS_IO.
	* sysdeps/pthread/pthread.h: Define bits for Unix98 variants of
	mutexes.
	* mutex.c: Implement new mutex types.
	* internals.h: Include <signal.h>.
	* libpthread.map: Add __erno_location and __h_errno_location.
	* errno.c: Return pointer to variable actually in use.  This might
	not be the one in the thread structure.
	* internals.h (struct _pthread_descr_struct): Add new fields p_errnop
	and p_h_errnop.
	* manager.c (__pthread_manager): Set p_errnop and p_h_errnop member
	of manager thread structure.
	(pthread_handle_create): Set p_errnop and p_h_errnop members for new
	thread.
	* pthread.c: Adapt initializer for thread structures.
	(__pthread_initial_thread): Set p_errnop and p_h_errnop member.
	(__pthread_reset_main_thread): Reset p_errnop and p_h_errnop of
	current thread to global variables.
1998-01-31 17:27  Ulrich Drepper  <drepper@cygnus.com>
	* rwlock.c: New file.
	* Makefile (libpthread-routines): Add rwlock.
	* sysdeps/pthread/pthread.h: Define data structures and declare
	functions.
	* libpthread.map: Add new functions.
1997-12-18 13:50  Philip Blundell  <pb@nexus.co.uk>
	* sysdeps/arm/pt-machine.h: New file; add ARM support.
	* sysdeps/arm/Implies: likewise.
	* README: Document it.
1997-12-13  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>
	* signals.c: Remove unneeded initializer for sigwaited, saving a
1997-04-11 01:18  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>
	* semaphore.c (sem_init): Set sem_spinlock only if available.
1997-12-04 01:48  Ulrich Drepper  <drepper@cygnus.com>
	* mutex.c: Implement PTHREAD_MUTEX_CHECKERROR.
	* sysdeps/pthread/pthread.h: Define PTHREAD_MUTEX_CHECKERROR.
	* Makefile: Update from LinuxThreads 0.7.
	* internals.h. Likewise.
	* manager.c: Likewise.
	* mutex.c: Likewise.
	* pthread.c: Likewise.
	* signals.c: Likewise.
	* specific.c: Likewise.
	* Examples/ex3.c: Likewise.
1997-11-20 18:13  Ulrich Drepper  <drepper@cygnus.com>
	* pthread.c (__pthread_reset_main_thread): Close pipe only if still
	open.
1997-10-29 05:38  Ulrich Drepper  <drepper@cygnus.com>

	* wrapsyscall.c: Add socket functions which are also cancelation
	points.

1997-10-19 21:40  Wolfram Gloger  <wg@wolfram.dent.med.uni-muenchen.de>

	* specific.c (__libc_internal_tsd_set, __libc_internal_tsd_get):
	New functions for fast thread specific data within libc.

	* internals.h: Add new array p_libc_specific to struct
	_pthread_descr_struct.

	* sysdeps/pthread/bits/libc-lock.h: Declare new functions.

1997-10-13 05:39  Ulrich Drepper  <drepper@cygnus.com>

	* semaphore.h: Add __BEGIN_DECLS/__END_DECLS.
	Reported by Ralf Corsepius <corsepiu@faw.uni-ulm.de>.

1997-08-29 03:05  Ulrich Drepper  <drepper@cygnus.com>

	* internals.h (struct _pthread_descr_struct): Add definitions for
	two-level specific key handling.
	* manager.c (pthread_handle_create): Initialize specific memory array.
	* specific.c: Implement two-level key handling.
	* weaks.c: Don't provide dummy key handling.
	* sysdeps/pthread/bits/libc-lock.h: Typedef __libc_lock_t (no #define).
	Add definition of __libc_key_t.
	* sysdeps/unix/sysv/linux/bits/local_lim.h: Define PTHREAD_KEYS_MAX
	as 1024.
	Add definition of _POSIX_THREAD_DESTRUCTOR_ITERATIONS and
	PTHREAD_DESTRUCTOR_ITERATIONS.

	* manager.c (pthread_handle_create): Compare mmap result with
	MAP_FAILED.

	* ptfork.c: Rename to __pthread_atfork and make old name a weak alias.
	* sysdeps/pthread/bits/pthread.h: Add prototype for __pthread_atfork.

1997-08-22 19:04  Richard Henderson  <rth@cygnus.com>

	sysdeps/sparc -> sysdeps/sparc/sparc32
	sysdeps/sparc64 -> sysdeps/sparc/sparc64

	* internals.h: Change definition of THREAD_SELF to be an expression,
	not a statement that did a return.
	* sysdeps/alpha/pt-machine.h (THREAD_SELF): Update accordingly.
	* sysdeps/sparc/sparc32/pt-machine.h (THREAD_SELF, INIT_THREAD_SELF):
	Follow Solaris and use a "system reserved" register (%g6) to hold
	the thread descriptor.
	* sysdeps/sparc/sparc64/pt-machine.h: Likewise.

1997-08-03 00:09  Ulrich Drepper  <drepper@cygnus.com>

	* mutex.c: Correct pthread_once.  Patch by Xavier Leroy.
	* sysdeps/pthread/pthread.h: Add prototype for __pthread_once.
	* sysdeps/pthread/bits/pthread.h: Add macros for __libc_once.

	* semaphore.c: Include spinlock.h only when needed.

	* specific.c (__pthread_setsepcific, __pthread_getspecific): Reject
	keys for entries not in use.

	* weaks.c: Implement key handling functions for real.

1997-06-29  01:04  Richard Henderson  <richard@gnu.ai.mit.edu>

	Initial sparc64-linux support:
	* linuxthreads/sysdeps/sparc64/Implies: New file.
	* linuxthreads/sysdeps/sparc64/pt-machine.h: Likewise.

1997-06-29 00:48  Ulrich Drepper  <drepper@cygnus.com>

	* semaphore.c: Include spinlock.h at correct place.
	Patch by HJ Lu.

1997-06-13 10:06  Richard Henderson  <rth@tamu.edu>

	The Great Bit File Move:
	* sysdeps/alpha/semaphorebits.h: -> .../bits/semaphore.h.
	* sysdeps/powerpc/semaphorebits.h: Likewise.
	* sysdeps/pthread/cmpxchg/semaphorebits.h: Likewise.
	* sysdeps/pthread/no-cmpxchg/semaphorebits.h: Likewise.
	* sysdeps/pthread/libc-lock.h: -> bits/
	* sysdeps/pthread/stdio-lock.h: Likewise.
	* sysdeps/unix/sysv/linux/local_lim.h: Likewise.
	* sysdeps/unix/sysv/linux/posix_opt.h: Likewise.
	* semaphore.h: Likewise.
	* sysdeps/pthread/pthread.h: Likewise.

	* lockfile.c: <foo.h> -> <bits/foo.h>.
	* semaphore.h: Likewise.

	* Makefile: (headers): foo.h -> bits/foo.h.
	* sysdeps/pthread/Makefile: Likewise.

1997-04-11 01:18  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* semaphore.c (sem_init): Set sem_spinlock only if available.

	* sysdeps/m68k/pt-machine.h (testandset, __compare_and_swap): Fix
	asm constraints.

1997-04-09 03:00  Ulrich Drepper  <drepper@cygnus.com>

	Update from LinuxThreads 0.6.

	* attr.c (pthread_attr_getdetachstate): Use __sched_get_priority_max
	and __sched_get_priority_min instead of names without `__'.

	* manager.c: Rewrite large parts to implement opaque pthread_t.

	* cancel.c: Adapt for opaque pthread_t type.
	* condvar.c: Likewise.
	* errno.c: Likewise.
	* join.c: Likewise.
	* mutex.c: Likewise.
	* pthread.c: Likewise.
	* signals.c: Likewise.
	* specific.c: Likewise.
	* restart.h: Likewise.
	* queue.h: Likewise.
	* Examples/ex3.c: Likewise.
	* Examples/ex4.c: Likewise.
	* sysdeps/pthread/pthread.h: Likewise.

	* pthread.c: Accumulate time for all threads in thread manager.

	* semaphore.c: Implement fallback implementation for architectures
	sometimes missing compare-exchange operations.

	* cancel.c (pthread_cancel): Validate handle argument.
	* join.c (pthread_join): Likewise.
	(pthread_detach): Likewise.
	* signals.c (pthread_kill): Likewise.

	* spinlock.h (acquire): Use __sched_yield not sched_yield.

	* queue.h (enqueue): Enqueue thread according to priority.

	* internals.c (struct pthread_start_args): New struct for passing
	args to cloning function.
	(struct _pthread): Rename to _pthread_descr_struct and adapt for
	opaque pthread_t.

	* Examples/Makefile (clean): Pass -f option to rm.

	* sysdeps/i386/pt-machine.h: Add check for compare-exchange instruction
	and define TEST_FOR_COMPARE_AND_SWAP.
	* sysdeps/i386/i486/pt-machine.h: Removed.

	* sysdeps/unix/sysv/linux/local_lim.h (PTHREAD_THREADS_MAX): Increase
	to 1024.

1997-04-04 16:38  Ulrich Drepper  <drepper@cygnus.com>

	* restart.h (suspend): Clear p_signal before suspending.
	(suspend_with_cancellation): Likewise.
	Patch by Xavier Leroy <Xavier.Leroy@inria.fr>.

	* weaks.c: Make __pthread_key_create return 1.
	* sysdeps/pthread/libc-lock.h: Define __libc_key_create,
	__libc_getspecific, __libc_setspecific, and __libc_key_t.
	* sysdeps/pthread/stdio-lock.h: Don't care for implementation not
	using libio.

1997-03-19 15:13  Miguel de Icaza  <miguel@nuclecu.unam.mx>

	* sysdeps/sparc/pt-machine (RELEASE): Fix.

1997-03-01 07:55  Geoff Keating  <geoffk@ozemail.com.au>

	* sysdeps/powerpc/Implies: Added.
	* sysdeps/powerpc/pt-machine.h: Added.
	* sysdeps/powerpc/semaphorebits.h: Added.

1997-01-22 01:22  Ulrich Drepper  <drepper@cygnus.com>

	* linuxtheads/pthread.c (__pthread_initial_thread): Correct
	initializer.
	(__pthread_manager_thread): Likewise.
	Reported by Andreas Jaeger.

1997-01-18 22:15  Richard Henderson  <rth@tamu.edu>

	Since sigset_t no longer fits in a register, we can't pass in the
	thread's initial mask so easily.  Take this opportunity to simplify
	the clone implementation by only accepting a single void* argument.

	* linuxthreads/manager.c (__pthread_manager): Put thread vitals
	in the thread struct instead of as arguments through clone.
	(pthread_start_thread): Look for them there.
	* linuxthreads/internals.h (struct _pthread): Add p_initial_fn,
	p_initial_fn_arg, p_initial_mask.  Fix __pthread_manager proto.
	* linuxthreads/pthread.c (pthread_initialize_manager): Revise
	clone invocation.
1998-03-11 12:42:25 +00:00

236 lines
7.0 KiB
Groff

.TH PTHREAD_COND 3 LinuxThreads
.XREF pthread_cond_signal
.XREF pthread_cond_broadcast
.XREF pthread_cond_wait
.XREF pthread_cond_timedwait
.XREF pthread_cond_destroy
.SH NAME
pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait \- operations on conditions
.SH SYNOPSIS
#include <pthread.h>
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *cond_attr);
int pthread_cond_signal(pthread_cond_t *cond);
int pthread_cond_broadcast(pthread_cond_t *cond);
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);
int pthread_cond_destroy(pthread_cond_t *cond);
.SH DESCRIPTION
A condition (short for ``condition variable'') is a synchronization
device that allows threads to suspend execution and relinquish the
processors 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.
!pthread_cond_init! initializes the condition variable |cond|, using the
condition attributes specified in |cond_attr|, or default attributes
if |cond_attr| is !NULL!. The LinuxThreads implementation supports no
attributes for conditions, hence the |cond_attr| parameter is actually
ignored.
Variables of type !pthread_cond_t! can also be initialized
statically, using the constant !PTHREAD_COND_INITIALIZER!.
!pthread_cond_signal! restarts one of the threads that are waiting on
the condition variable |cond|. If no threads are waiting on |cond|,
nothing happens. If several threads are waiting on |cond|, exactly one
is restarted, but it is not specified which.
!pthread_cond_broadcast! restarts all the threads that are waiting on
the condition variable |cond|. Nothing happens if no threads are
waiting on |cond|.
!pthread_cond_wait! atomically unlocks the |mutex| (as per
!pthread_unlock_mutex!) and waits for the condition variable |cond| to
be signaled. The thread execution is suspended and does not consume
any CPU time until the condition variable is signaled. The |mutex|
must be locked by the calling thread on entrance to
!pthread_cond_wait!. Before returning to the calling thread,
!pthread_cond_wait! re-acquires |mutex| (as per !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.
!pthread_cond_timedwait! atomically unlocks |mutex| and waits on
|cond|, as !pthread_cond_wait! does, but it also bounds the duration
of the wait. If |cond| has not been signaled within the amount of time
specified by |abstime|, the mutex |mutex| is re-acquired and
!pthread_cond_timedwait! returns the error !ETIMEDOUT!.
The |abstime| parameter specifies an absolute time, with the same
origin as !time!(2) and !gettimeofday!(2): an |abstime| of 0
corresponds to 00:00:00 GMT, January 1, 1970.
!pthread_cond_destroy! destroys a condition variable, freeing the
resources it might hold. No threads must be waiting on the condition
variable on entrance to !pthread_cond_destroy!. In the LinuxThreads
implementation, no resources are associated with condition variables,
thus !pthread_cond_destroy! actually does nothing except checking that
the condition has no waiting threads.
.SH CANCELLATION
!pthread_cond_wait! and !pthread_cond_timedwait! are cancellation
points. If a thread is cancelled while suspended in one of these
functions, the thread immediately resumes execution, then locks again
the |mutex| argument to !pthread_cond_wait! and
!pthread_cond_timedwait!, and finally executes the cancellation.
Consequently, cleanup handlers are assured that |mutex| is locked when
they are called.
.SH "ASYNC-SIGNAL SAFETY"
The condition functions are not async-signal safe, and should not be
called from a signal handler. In particular, calling
!pthread_cond_signal! or !pthread_cond_broadcast! from a signal
handler may deadlock the calling thread.
.SH "RETURN VALUE"
All condition variable functions return 0 on success and a non-zero
error code on error.
.SH ERRORS
!pthread_cond_init!, !pthread_cond_signal!, !pthread_cond_broadcast!,
and !pthread_cond_wait! never return an error code.
The !pthread_cond_timedwait! function returns the following error codes
on error:
.RS
.TP
!ETIMEDOUT!
the condition variable was not signaled until the timeout specified by
|abstime|
.TP
!EINTR!
!pthread_cond_timedwait! was interrupted by a signal
.RE
The !pthread_cond_destroy! function returns the following error code
on error:
.RS
.TP
!EBUSY!
some threads are currently waiting on |cond|.
.RE
.SH AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>
.SH "SEE ALSO"
!pthread_condattr_init!(3),
!pthread_mutex_lock!(3),
!pthread_mutex_unlock!(3),
!gettimeofday!(2),
!nanosleep!(2).
.SH EXAMPLE
Consider two shared variables |x| and |y|, protected by the mutex |mut|,
and a condition variable |cond| that is to be signaled whenever |x|
becomes greater than |y|.
.RS
.ft 3
.nf
.sp
int x,y;
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
.ft
.LP
.RE
.fi
Waiting until |x| is greater than |y| is performed as follows:
.RS
.ft 3
.nf
.sp
pthread_mutex_lock(&mut);
while (x <= y) {
pthread_cond_wait(&cond, &mut);
}
/* operate on x and y */
pthread_mutex_unlock(&mut);
.ft
.LP
.RE
.fi
Modifications on |x| and |y| that may cause |x| to become greater than
|y| should signal the condition if needed:
.RS
.ft 3
.nf
.sp
pthread_mutex_lock(&mut);
/* modify x and y */
if (x > y) pthread_mutex_broadcast(&cond);
pthread_mutex_unlock(&mut);
.ft
.LP
.RE
.fi
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
|x| and |y|), !pthread_cond_signal! can be used as a slightly more
efficient alternative to !pthread_cond_broadcast!. In doubt, use
!pthread_cond_broadcast!.
To wait for |x| to becomes greater than |y| with a timeout of 5
seconds, do:
.RS
.ft 3
.nf
.sp
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);
.ft
.LP
.RE
.fi