1.\" $NetBSD: pthread_cond.3,v 1.5 2010/07/09 20:56:01 wiz Exp $ 2.\" 3.\" Copyright (c) 2002, 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> 28.\" All rights reserved. 29.\" 30.\" Redistribution and use in source and binary forms, with or without 31.\" modification, are permitted provided that the following conditions 32.\" are met: 33.\" 1. Redistributions of source code must retain the above copyright 34.\" notice, this list of conditions and the following disclaimer. 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in the 37.\" documentation and/or other materials provided with the distribution. 38.\" 3. Neither the name of the author nor the names of any co-contributors 39.\" may be used to endorse or promote products derived from this software 40.\" without specific prior written permission. 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 43.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 45.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 46.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 47.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 48.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 50.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 51.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 52.\" SUCH DAMAGE. 53.\" 54.\" ---------------------------------------------------------------------------- 55.Dd July 8, 2010 56.Dt PTHREAD_COND 3 57.Os 58.Sh NAME 59.Nm pthread_cond 60.Nd condition variable interface 61.Sh LIBRARY 62.Lb libpthread 63.\" ---------------------------------------------------------------------------- 64.Sh SYNOPSIS 65.In pthread.h 66.Ft int 67.Fn pthread_cond_init "pthread_cond_t * restrict cond" \ 68"const pthread_condattr_t * restrict attr" 69.Ft int 70.Fn pthread_cond_destroy "pthread_cond_t *cond" 71.Ft int 72.Fn pthread_cond_broadcast "pthread_cond_t *cond" 73.Ft int 74.Fn pthread_cond_signal "pthread_cond_t *cond" 75.Ft int 76.Fn pthread_cond_wait "pthread_cond_t * restrict cond" \ 77"pthread_mutex_t * restrict mutex" 78.Ft int 79.Fn pthread_cond_timedwait "pthread_cond_t * restrict cond" \ 80"pthread_mutex_t * restrict mutex" "const struct timespec * restrict abstime" 81.Pp 82.Va pthread_cond_t cond = Dv PTHREAD_COND_INITIALIZER; 83.\" ---------------------------------------------------------------------------- 84.Sh DESCRIPTION 85Condition variables are intended to be used to communicate changes in 86the state of data shared between threads. 87Condition variables are always associated with a mutex to provide 88synchronized access to the shared data. 89A single predicate should always be associated with a 90condition variable. 91The predicate should identify a state of the 92shared data that must be true before the thread proceeds. 93.Pp 94The 95.Fn pthread_cond_init 96function creates a new condition variable, with attributes specified with 97.Fa attr . 98If 99.Fa attr 100is 101.Dv NULL 102the default attributes are used. 103The 104.Fn pthread_cond_destroy 105function frees the resources allocated by the condition variable 106.Fa cond . 107.Pp 108The macro 109.Dv PTHREAD_COND_INITIALIZER 110can be used to initialize a condition variable when it can be statically 111allocated and the default attributes are appropriate. 112The effect is similar to calling 113.Fn pthread_cond_init 114with 115.Fa attr 116specified as 117.Dv NULL , 118except that no error checking is done. 119.Pp 120.\" ----- 121The difference between 122.Fn pthread_cond_broadcast 123and 124.Fn pthread_cond_signal 125is that the former unblocks all threads waiting for the condition variable, 126whereas the latter blocks only one waiting thread. 127If no threads are waiting on 128.Fa cond , 129neither function has any effect. 130If more than one thread is blocked on a condition variable, 131the used scheduling policy determines the order in which threads are unblocked. 132The same mutex used for waiting must be held while calling either function. 133Although neither function strictly enforces this requirement, 134undefined behavior may follow if the mutex is not held. 135.Pp 136.\" ----- 137The 138.Fn pthread_cond_wait 139function atomically blocks the current thread waiting on the condition 140variable specified by 141.Fa cond , 142and unlocks the mutex specified by 143.Fa mutex . 144The 145.Fn pthread_cond_timedwait 146function behaves similarly, but unblocks also 147if the system time reaches the time specified in 148.Fa abstime , 149represented as 150.Em struct timespec 151(see 152.Xr timespec 3 ) . 153With both functions the waiting thread unblocks after another thread calls 154.Fn pthread_cond_signal 155or 156.Fn pthread_cond_broadcast 157with the same condition variable and by holding the same 158.Fa mutex 159that was associated with 160.Fa cond 161by either one of the blocking functions. 162The current thread holds the lock on 163.Fa mutex 164upon return from either function. 165.\" ----- 166.Pp 167Note that a call to 168.Fn pthread_cond_wait 169or 170.Fn pthread_cond_timedwait 171may wake up spontaneously, without a call to 172.Fn pthread_cond_signal 173or 174.Fn pthread_cond_broadcast . 175The caller should prepare for this by invoking either function 176within a predicate loop that tests whether the thread should proceed. 177.Pp 178.\" ----- 179As noted, when calling either function that waits on a condition variable, 180a temporary binding is established between the condition variable 181.Fa cond 182and the mutex 183.Fa mutex . 184During this time, the effect of an attempt by any thread to wait on 185that condition variable using a different mutex is undefined. 186The same mutex must be held while broadcasting or signaling on 187.Fa cond . 188Additionally, the same mutex must be used for concurrent calls to 189.Fn pthread_cond_wait 190and 191.Fn pthread_cond_timedwait . 192Only when a condition variable is known to be quiescent may an application 193change the mutex associated with it. 194In this implementation, none of the functions enforce this requirement, but 195if the mutex is not held or independent mutexes are used the resulting 196behaviour is undefined. 197.\" ---------------------------------------------------------------------------- 198.Sh RETURN VALUES 199If successful, all functions return zero. 200Otherwise, an error number will be returned to indicate the error. 201.Sh ERRORS 202The 203.Fn pthread_cond_init 204function may fail if: 205.Bl -tag -width Er 206.It Bq Er EINVAL 207The value specified by 208.Fa attr 209is invalid. 210.El 211.Pp 212.\" ----- 213The 214.Fn pthread_cond_destroy 215function may fail if: 216.Bl -tag -width Er 217.It Bq Er EBUSY 218The variable 219.Fa cond 220is locked by another thread. 221.It Bq Er EINVAL 222The value specified by 223.Fa cond 224is invalid. 225.El 226.Pp 227.\" ----- 228Both 229.Fn pthread_cond_broadcast 230and 231.Fn pthread_cond_signal 232may fail if: 233.Bl -tag -width Er 234.It Bq Er EINVAL 235The value specified by 236.Fa cond 237is invalid. 238.El 239.Pp 240.\" ----- 241Both 242.Fn pthread_cond_wait 243and 244.Fn pthread_cond_timedwait 245may fail if: 246.Bl -tag -width Er 247.It Bq Er EINVAL 248The value specified by 249.Fa cond 250or the value specified by 251.Fa mutex 252is invalid. 253.It Bq Er EPERM 254The value specified by 255.Fa mutex 256was not locked in the condition wait. 257.El 258.Pp 259The 260.Fn pthread_cond_timedwait 261function may additionally fail if: 262.Bl -tag -width Er 263.It Bq Er ETIMEDOUT 264The system time has reached or exceeded the time specified in 265.Fa abstime . 266.El 267.Sh SEE ALSO 268.Xr pthread 3 , 269.Xr pthread_barrier 3 , 270.Xr pthread_condattr 3 , 271.Xr pthread_mutex 3 , 272.Xr pthread_rwlock 3 , 273.Xr pthread_spin 3 274.Sh STANDARDS 275These functions conform to 276.St -p1003.1-2001 . 277