New upstream version 18.0.1+dfsg1
This commit is contained in:
Sebastian Ramacher
parent
6efda2859e
commit
f2cf6cce50
1337 changed files with 41178 additions and 84670 deletions
313
deps/w32-pthreads/manual/pthread_cond_init.html
vendored
313
deps/w32-pthreads/manual/pthread_cond_init.html
vendored
|
|
@ -1,313 +0,0 @@
|
|||
<!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>
|
||||
Loading…
Add table
Add a link
Reference in a new issue