314 lines
13 KiB
HTML
314 lines
13 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|||
|
|
<HTML>
|
|||
|
|
<HEAD>
|
|||
|
|
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
|
|||
|
|
<TITLE>PTHREAD_COND(3) manual page</TITLE>
|
|||
|
|
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
|
|||
|
|
<META NAME="CREATED" CONTENT="20050504;16454400">
|
|||
|
|
<META NAME="CHANGED" CONTENT="20050505;19004700">
|
|||
|
|
<!-- manual page source format generated by PolyglotMan v3.2, -->
|
|||
|
|
<!-- available at http://polyglotman.sourceforge.net/ -->
|
|||
|
|
</HEAD>
|
|||
|
|
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
|
|||
|
|
<H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
|
|||
|
|
<P><A HREF="index.html">Reference Index</A></P>
|
|||
|
|
<P><A HREF="#toc">Table of Contents</A></P>
|
|||
|
|
<H2><A HREF="#toc0" NAME="sect0">Name</A></H2>
|
|||
|
|
<P>pthread_cond_init, pthread_cond_destroy, pthread_cond_signal,
|
|||
|
|
pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait -
|
|||
|
|
operations on conditions
|
|||
|
|
</P>
|
|||
|
|
<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
|
|||
|
|
<P><B>#include <pthread.h></B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>pthread_cond_t </B><I>cond</I> <B>= PTHREAD_COND_INITIALIZER;</B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>int pthread_cond_init(pthread_cond_t *</B><I>cond</I><B>,
|
|||
|
|
pthread_condattr_t *</B><I>cond_attr</I><B>);</B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>int pthread_cond_signal(pthread_cond_t *</B><I>cond</I><B>);</B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>int pthread_cond_broadcast(pthread_cond_t *</B><I>cond</I><B>);</B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>int pthread_cond_wait(pthread_cond_t *</B><I>cond</I><B>,
|
|||
|
|
pthread_mutex_t *</B><I>mutex</I><B>);</B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>int pthread_cond_timedwait(pthread_cond_t *</B><I>cond</I><B>,
|
|||
|
|
pthread_mutex_t *</B><I>mutex</I><B>, const struct timespec
|
|||
|
|
*</B><I>abstime</I><B>);</B>
|
|||
|
|
</P>
|
|||
|
|
<P><B>int pthread_cond_destroy(pthread_cond_t *</B><I>cond</I><B>);</B>
|
|||
|
|
</P>
|
|||
|
|
<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
|
|||
|
|
<P>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.
|
|||
|
|
</P>
|
|||
|
|
<P>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.
|
|||
|
|
</P>
|
|||
|
|
<P><B>pthread_cond_init</B> initializes the condition variable <I>cond</I>,
|
|||
|
|
using the condition attributes specified in <I>cond_attr</I>, or
|
|||
|
|
default attributes if <I>cond_attr</I> is <B>NULL</B>.
|
|||
|
|
</P>
|
|||
|
|
<P>Variables of type <B>pthread_cond_t</B> can also be initialized
|
|||
|
|
statically, using the constant <B>PTHREAD_COND_INITIALIZER</B>. In
|
|||
|
|
the <B>Pthreads-w32</B> implementation, an application should still
|
|||
|
|
call <B>pthread_cond_destroy</B> at some point to ensure that any
|
|||
|
|
resources consumed by the condition variable are released.</P>
|
|||
|
|
<P><B>pthread_cond_signal</B> restarts one of the threads that are
|
|||
|
|
waiting on the condition variable <I>cond</I>. If no threads are
|
|||
|
|
waiting on <I>cond</I>, nothing happens. If several threads are
|
|||
|
|
waiting on <I>cond</I>, exactly one is restarted, but it is not
|
|||
|
|
specified which.
|
|||
|
|
</P>
|
|||
|
|
<P><B>pthread_cond_broadcast</B> restarts all the threads that are
|
|||
|
|
waiting on the condition variable <I>cond</I>. Nothing happens if no
|
|||
|
|
threads are waiting on <I>cond</I>.
|
|||
|
|
</P>
|
|||
|
|
<P><B>pthread_cond_wait</B> atomically unlocks the <I>mutex</I> (as
|
|||
|
|
per <B>pthread_unlock_mutex</B>) and waits for the condition variable
|
|||
|
|
<I>cond</I> to be signalled. The thread execution is suspended and
|
|||
|
|
does not consume any CPU time until the condition variable is
|
|||
|
|
signalled. The <I>mutex</I> must be locked by the calling thread on
|
|||
|
|
entrance to <B>pthread_cond_wait</B>. Before returning to the calling
|
|||
|
|
thread, <B>pthread_cond_wait</B> re-acquires <I>mutex</I> (as per
|
|||
|
|
<B>pthread_lock_mutex</B>).
|
|||
|
|
</P>
|
|||
|
|
<P>Unlocking the mutex and suspending on the condition variable is
|
|||
|
|
done atomically. Thus, if all threads always acquire the mutex before
|
|||
|
|
signalling the condition, this guarantees that the condition cannot
|
|||
|
|
be signalled (and thus ignored) between the time a thread locks the
|
|||
|
|
mutex and the time it waits on the condition variable.
|
|||
|
|
</P>
|
|||
|
|
<P><B>pthread_cond_timedwait</B> atomically unlocks <I>mutex</I> and
|
|||
|
|
waits on <I>cond</I>, as <B>pthread_cond_wait</B> does, but it also
|
|||
|
|
bounds the duration of the wait. If <I>cond</I> has not been
|
|||
|
|
signalled within the amount of time specified by <I>abstime</I>, the
|
|||
|
|
mutex <I>mutex</I> is re-acquired and <B>pthread_cond_timedwait</B>
|
|||
|
|
returns the error <B>ETIMEDOUT</B>. The <I>abstime</I> parameter
|
|||
|
|
specifies an absolute time, with the same origin as <A HREF="time.html"><B>time</B>(2)</A>
|
|||
|
|
and <A HREF="gettimeofday.html"><B>gettimeofday</B>(2)</A>.
|
|||
|
|
</P>
|
|||
|
|
<P><B>pthread_cond_destroy</B> destroys a condition variable, freeing
|
|||
|
|
the resources it might hold. No threads must be waiting on the
|
|||
|
|
condition variable on entrance to <B>pthread_cond_destroy</B>.</P>
|
|||
|
|
<H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
|
|||
|
|
<P><B>pthread_cond_wait</B> and <B>pthread_cond_timedwait</B> are
|
|||
|
|
cancellation points. If a thread is cancelled while suspended in one
|
|||
|
|
of these functions, the thread immediately resumes execution, then
|
|||
|
|
locks again the <I>mutex</I> argument to <B>pthread_cond_wait</B> and
|
|||
|
|
<B>pthread_cond_timedwait</B>, and finally executes the cancellation.
|
|||
|
|
Consequently, cleanup handlers are assured that <I>mutex</I> is
|
|||
|
|
locked when they are called.
|
|||
|
|
</P>
|
|||
|
|
<H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2>
|
|||
|
|
<P>The condition functions are not async-signal safe, and should not
|
|||
|
|
be called from a signal handler. In particular, calling
|
|||
|
|
<B>pthread_cond_signal</B> or <B>pthread_cond_broadcast</B> from a
|
|||
|
|
signal handler may deadlock the calling thread.
|
|||
|
|
</P>
|
|||
|
|
<H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2>
|
|||
|
|
<P>All condition variable functions return 0 on success and a
|
|||
|
|
non-zero error code on error.
|
|||
|
|
</P>
|
|||
|
|
<H2><A HREF="#toc6" NAME="sect6">Errors</A></H2>
|
|||
|
|
<P><B>pthread_cond_init</B>, <B>pthread_cond_signal</B>,
|
|||
|
|
<B>pthread_cond_broadcast</B>, and <B>pthread_cond_wait</B> never
|
|||
|
|
return an error code.
|
|||
|
|
</P>
|
|||
|
|
<P>The <B>pthread_cond_init</B> function returns the following error
|
|||
|
|
codes on error:
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
|
|||
|
|
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
The <I>cond</I> argument is invalid.
|
|||
|
|
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
<B>ENOMEM</B>
|
|||
|
|
</DT></DL>
|
|||
|
|
</DL>
|
|||
|
|
<BLOCKQUOTE STYLE="margin-left: 4cm">
|
|||
|
|
There was not enough memory to allocate the condition variable.
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<P>The <B>pthread_cond_signal</B> function returns the following
|
|||
|
|
error codes on error:
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
|
|||
|
|
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
The <I>cond</I> argument is invalid.
|
|||
|
|
</DD></DL>
|
|||
|
|
</DL>
|
|||
|
|
<P>
|
|||
|
|
The <B>pthread_cond_broadcast</B> function returns the following
|
|||
|
|
error codes on error:
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
|
|||
|
|
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
The <I>cond</I> argument is invalid.
|
|||
|
|
</DD></DL>
|
|||
|
|
</DL>
|
|||
|
|
<P>
|
|||
|
|
The <B>pthread_cond_wait</B> function returns the following error
|
|||
|
|
codes on error:
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
|
|||
|
|
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
The <I>cond</I> argument is invalid.
|
|||
|
|
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
<B>ENOMEM</B>
|
|||
|
|
</DT></DL>
|
|||
|
|
</DL>
|
|||
|
|
<BLOCKQUOTE STYLE="margin-left: 4cm">
|
|||
|
|
There was not enough memory to allocate the statically initialised
|
|||
|
|
condition variable. Statically initialised condition variables are
|
|||
|
|
dynamically allocated by the first thread to wait on them.</BLOCKQUOTE>
|
|||
|
|
<P>The <B>pthread_cond_timedwait</B> function returns the following
|
|||
|
|
error codes on error:
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
|
|||
|
|
</DT></DL>
|
|||
|
|
</DL>
|
|||
|
|
<P STYLE="margin-left: 2cm">
|
|||
|
|
The <I>cond</I> argument is invalid.
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B>
|
|||
|
|
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
The condition variable was not signalled before the timeout
|
|||
|
|
specified by <I>abstime</I>
|
|||
|
|
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
<B>ENOMEM</B>
|
|||
|
|
</DT></DL>
|
|||
|
|
</DL>
|
|||
|
|
<BLOCKQUOTE STYLE="margin-left: 4cm">
|
|||
|
|
There was not enough memory to allocate the statically initialised
|
|||
|
|
condition variable. Statically initialised condition variables are
|
|||
|
|
dynamically allocated by the first thread to wait on them.
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<P>The <B>pthread_cond_destroy</B> function returns the following
|
|||
|
|
error code on error:
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
|
|||
|
|
</DT></DL>
|
|||
|
|
</DL>
|
|||
|
|
<P STYLE="margin-left: 2cm; margin-right: 1cm">
|
|||
|
|
The <I>cond</I> argument is invalid.
|
|||
|
|
</P>
|
|||
|
|
<DL>
|
|||
|
|
<DL>
|
|||
|
|
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B>
|
|||
|
|
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
|
|||
|
|
Some threads are currently waiting on <I>cond</I>.
|
|||
|
|
</DD></DL>
|
|||
|
|
</DL>
|
|||
|
|
<H2>
|
|||
|
|
<A HREF="#toc7" NAME="sect7">Author</A></H2>
|
|||
|
|
<P>Xavier Leroy <Xavier.Leroy@inria.fr>
|
|||
|
|
</P>
|
|||
|
|
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
|
|||
|
|
<H2><A HREF="#toc8" NAME="sect8">See Also</A></H2>
|
|||
|
|
<P><A HREF="pthread_condattr_init.html"><B>pthread_condattr_init</B>(3)</A>
|
|||
|
|
, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
|
|||
|
|
, <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
|
|||
|
|
, <A HREF="pthread_cancel.html"><B>pthread_cancel(3)</B></A>.
|
|||
|
|
</P>
|
|||
|
|
<H2><A HREF="#toc9" NAME="sect9">Example</A></H2>
|
|||
|
|
<P>Consider two shared variables <I>x</I> and <I>y</I>, protected by
|
|||
|
|
the mutex <I>mut</I>, and a condition variable <I>cond</I> that is to
|
|||
|
|
be signaled whenever <I>x</I> becomes greater than <I>y</I>.
|
|||
|
|
</P>
|
|||
|
|
<PRE STYLE="margin-left: 1cm; margin-right: 1cm">int x,y;
|
|||
|
|
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
|
|||
|
|
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;</PRE><BLOCKQUOTE>
|
|||
|
|
Waiting until <I>x</I> is greater than <I>y</I> is performed as
|
|||
|
|
follows:
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&mut);
|
|||
|
|
while (x <= y) {
|
|||
|
|
pthread_cond_wait(&cond, &mut);
|
|||
|
|
}
|
|||
|
|
/* operate on x and y */
|
|||
|
|
pthread_mutex_unlock(&mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
|
|||
|
|
Modifications on <I>x</I> and <I>y</I> that may cause <I>x</I> to
|
|||
|
|
become greater than <I>y</I> should signal the condition if needed:
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<PRE STYLE="margin-left: 1.01cm">pthread_mutex_lock(&mut);
|
|||
|
|
/* modify x and y */
|
|||
|
|
if (x > y) pthread_cond_broadcast(&cond);
|
|||
|
|
pthread_mutex_unlock(&mut);</PRE><BLOCKQUOTE STYLE="margin-left: 3.01cm">
|
|||
|
|
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
|
|||
|
|
<I>x</I> and <I>y</I>), <B>pthread_cond_signal</B> can be used as a
|
|||
|
|
slightly more efficient alternative to <B>pthread_cond_broadcast</B>.
|
|||
|
|
If in doubt, use <B>pthread_cond_broadcast</B>.
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<BLOCKQUOTE STYLE="margin-left: 3.01cm">To wait for <I>x</I> to
|
|||
|
|
become greater than <I>y</I> with a timeout of 5 seconds, do:
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<PRE STYLE="margin-left: 1.01cm">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);</PRE>
|
|||
|
|
<HR>
|
|||
|
|
<BLOCKQUOTE STYLE="margin-left: 0cm; margin-right: 0cm"><A NAME="toc"></A>
|
|||
|
|
<B>Table of Contents</B></BLOCKQUOTE>
|
|||
|
|
<UL>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal
|
|||
|
|
Safety</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return
|
|||
|
|
Value</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm; margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">See
|
|||
|
|
Also</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
<LI><BLOCKQUOTE STYLE="margin-right: 0cm"><A HREF="#sect9" NAME="toc9">Example</A>
|
|||
|
|
</BLOCKQUOTE>
|
|||
|
|
</UL>
|
|||
|
|
</BODY>
|
|||
|
|
</HTML>
|