1.\" $NetBSD: pthread_cond.3,v 1.9 2018/07/28 14:00:19 kre 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.Nm pthread_cond_init , 61.Nm pthread_cond_destroy , 62.Nm pthread_cond_broadcast , 63.Nm pthread_cond_signal , 64.Nm pthread_cond_wait , 65.Nm pthread_cond_timedwait 66.Nd condition variable interface 67.Sh LIBRARY 68.Lb libpthread 69.\" ---------------------------------------------------------------------------- 70.Sh SYNOPSIS 71.In pthread.h 72.Ft int 73.Fn pthread_cond_init "pthread_cond_t * restrict cond" \ 74"const pthread_condattr_t * restrict attr" 75.Vt pthread_cond_t cond No = Dv PTHREAD_COND_INITIALIZER ; 76.Ft int 77.Fn pthread_cond_destroy "pthread_cond_t *cond" 78.Ft int 79.Fn pthread_cond_broadcast "pthread_cond_t *cond" 80.Ft int 81.Fn pthread_cond_signal "pthread_cond_t *cond" 82.Ft int 83.Fn pthread_cond_wait "pthread_cond_t * restrict cond" \ 84"pthread_mutex_t * restrict mutex" 85.Ft int 86.Fn pthread_cond_timedwait "pthread_cond_t * restrict cond" \ 87"pthread_mutex_t * restrict mutex" "const struct timespec * restrict abstime" 88.\" ---------------------------------------------------------------------------- 89.Sh DESCRIPTION 90Condition variables are intended to be used to communicate changes in 91the state of data shared between threads. 92Condition variables are always associated with a mutex to provide 93synchronized access to the shared data. 94A single predicate should always be associated with a 95condition variable. 96The predicate should identify a state of the 97shared data that must be true before the thread proceeds. 98.Pp 99The 100.Fn pthread_cond_init 101function creates a new condition variable, with attributes specified with 102.Fa attr . 103If 104.Fa attr 105is 106.Dv NULL 107the default attributes are used. 108The 109.Fn pthread_cond_destroy 110function frees the resources allocated by the condition variable 111.Fa cond . 112.Pp 113The macro 114.Dv PTHREAD_COND_INITIALIZER 115can be used to initialize a condition variable when it can be statically 116allocated and the default attributes are appropriate. 117The effect is similar to calling 118.Fn pthread_cond_init 119with 120.Fa attr 121specified as 122.Dv NULL , 123except that no error checking is done. 124.Pp 125.\" ----- 126The difference between 127.Fn pthread_cond_broadcast 128and 129.Fn pthread_cond_signal 130is that the former unblocks all threads waiting for the condition variable, 131whereas the latter unblocks only one waiting thread. 132If no threads are waiting on 133.Fa cond , 134neither function has any effect. 135If more than one thread is blocked on a condition variable, 136the used scheduling policy determines the order in which threads are unblocked. 137The same mutex used for waiting must be held while calling either function. 138Although neither function strictly enforces this requirement, 139undefined behavior may follow if the mutex is not held. 140.Pp 141.\" ----- 142The 143.Fn pthread_cond_wait 144function atomically blocks the current thread waiting on the condition 145variable specified by 146.Fa cond , 147and unlocks the mutex specified by 148.Fa mutex . 149The 150.Fn pthread_cond_timedwait 151function behaves similarly, but unblocks also 152if the system time reaches the time specified in 153.Fa abstime , 154represented as 155.Em struct timespec 156(see 157.Xr timespec 3 ) . 158With both functions the waiting thread unblocks after another thread calls 159.Fn pthread_cond_signal 160or 161.Fn pthread_cond_broadcast 162with the same condition variable and by holding the same 163.Fa mutex 164that was associated with 165.Fa cond 166by either one of the blocking functions. 167The current thread holds the lock on 168.Fa mutex 169upon return from either function. 170.\" ----- 171.Pp 172Note that a call to 173.Fn pthread_cond_wait 174or 175.Fn pthread_cond_timedwait 176may wake up spontaneously, without a call to 177.Fn pthread_cond_signal 178or 179.Fn pthread_cond_broadcast . 180The caller should prepare for this by invoking either function 181within a predicate loop that tests whether the thread should proceed. 182.Pp 183.\" ----- 184As noted, when calling either function that waits on a condition variable, 185a temporary binding is established between the condition variable 186.Fa cond 187and the mutex 188.Fa mutex . 189During this time, the effect of an attempt by any thread to wait on 190that condition variable using a different mutex is undefined. 191The same mutex must be held while broadcasting or signaling on 192.Fa cond . 193Additionally, the same mutex must be used for concurrent calls to 194.Fn pthread_cond_wait 195and 196.Fn pthread_cond_timedwait . 197Only when a condition variable is known to be quiescent may an application 198change the mutex associated with it. 199In this implementation, none of the functions enforce this requirement, but 200if the mutex is not held or independent mutexes are used the resulting 201behaviour is undefined. 202.\" ---------------------------------------------------------------------------- 203.Sh RETURN VALUES 204If successful, all functions return zero. 205Otherwise, an error number will be returned to indicate the error. 206.Sh ERRORS 207The 208.Fn pthread_cond_init 209function may fail if: 210.Bl -tag -width Er 211.It Bq Er EINVAL 212The value specified by 213.Fa attr 214is invalid. 215.El 216.Pp 217.\" ----- 218The 219.Fn pthread_cond_destroy 220function may fail if: 221.Bl -tag -width Er 222.It Bq Er EBUSY 223The variable 224.Fa cond 225is locked by another thread. 226.It Bq Er EINVAL 227The value specified by 228.Fa cond 229is invalid. 230.El 231.Pp 232.\" ----- 233Both 234.Fn pthread_cond_broadcast 235and 236.Fn pthread_cond_signal 237may fail if: 238.Bl -tag -width Er 239.It Bq Er EINVAL 240The value specified by 241.Fa cond 242is invalid. 243.El 244.Pp 245.\" ----- 246Both 247.Fn pthread_cond_wait 248and 249.Fn pthread_cond_timedwait 250may fail if: 251.Bl -tag -width Er 252.It Bq Er EINVAL 253The value specified by 254.Fa cond 255or the value specified by 256.Fa mutex 257is invalid. 258.It Bq Er EPERM 259The value specified by 260.Fa mutex 261was not locked in the condition wait. 262.El 263.Pp 264The 265.Fn pthread_cond_timedwait 266function may additionally fail if: 267.Bl -tag -width Er 268.It Bq Er ETIMEDOUT 269The system time has reached or exceeded the time specified in 270.Fa abstime . 271.El 272.Sh SEE ALSO 273.Xr pthread 3 , 274.Xr pthread_barrier 3 , 275.Xr pthread_condattr 3 , 276.Xr pthread_mutex 3 , 277.Xr pthread_rwlock 3 , 278.Xr pthread_spin 3 279.Sh STANDARDS 280These functions conform to 281.St -p1003.1-2001 . 282