diff options
Diffstat (limited to 'pthreads/manual/pthread_cond_init.html')
| -rw-r--r-- | pthreads/manual/pthread_cond_init.html | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/pthreads/manual/pthread_cond_init.html b/pthreads/manual/pthread_cond_init.html new file mode 100644 index 000000000..937e490a0 --- /dev/null +++ b/pthreads/manual/pthread_cond_init.html @@ -0,0 +1,313 @@ +<!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> |