Copyright (c) 2002, 2008 The NetBSD Foundation, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Copyright (c) 1997 Brian Cully <shmit@kublai.com>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the author nor the names of any co-contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
----------------------------------------------------------------------------
.Dd July 8, 2010 .Dt PTHREAD_COND 3 .Os .Sh NAME .Nm pthread_cond .Nd condition variable interface .Sh LIBRARY .Lb libpthread ----------------------------------------------------------------------------
.Sh SYNOPSIS n pthread.h .Ft int .Fn pthread_cond_init "pthread_cond_t * restrict cond" \ "const pthread_condattr_t * restrict attr"
p
.Va pthread_cond_t cond = Dv PTHREAD_COND_INITIALIZER;
.Ft int
.Fn pthread_cond_destroy "pthread_cond_t *cond"
.Ft int
.Fn pthread_cond_broadcast "pthread_cond_t *cond"
.Ft int
.Fn pthread_cond_signal "pthread_cond_t *cond"
.Ft int
.Fn pthread_cond_wait "pthread_cond_t * restrict cond" \
"pthread_mutex_t * restrict mutex"
.Ft int
.Fn pthread_cond_timedwait "pthread_cond_t * restrict cond" \
"pthread_mutex_t * restrict mutex" "const struct timespec * restrict abstime"
----------------------------------------------------------------------------
.Sh DESCRIPTION
The
.Fn pthread_cond_init
function creates a new condition variable, with attributes specified with
.Fa attr .
If
.Fa attr
is NULL the default attributes are used.
p Condition variables are intended to be used to communicate changes in the state of data shared between threads. Condition variables are always associated with a mutex to provide synchronized access to the shared data. A single predicate should always be associated with a condition variable. The predicate should identify a state of the shared data that must be true before the thread proceeds.
p The macro .Dv PTHREAD_COND_INITIALIZER can be used to initialize a condition variable when it can be statically allocated and the default attributes are appropriate. The effect is similar to calling .Fn pthread_cond_init with .Fa attr specified as .Dv NULL , except that no error checking is done.
p
-----
The
.Fn pthread_cond_destroy
function frees the resources allocated by the condition variable
.Fa cond .
p
-----
The
.Fn pthread_cond_broadcast
function unblocks all threads waiting for the condition variable
.Fa cond .
If no threads are waiting on
.Fa cond ,
the
.Fn pthread_cond_broadcast
function has no effect.
p The .Fn pthread_cond_signal function unblocks one thread waiting for the condition variable .Fa cond . If no threads are waiting on .Fa cond , the .Fn pthread_cond_signal function has no effect.
p When calling .Fn pthread_cond_wait and/or .Fn pthread_cond_timedwait , a temporary binding is established between the condition variable .Fa cond and a caller-supplied mutex.
p The same mutex must be held while calling .Fn pthread_cond_broadcast and .Fn pthread_cond_signal . Neither function enforces this requirement, but if the mutex is not held the resulting behaviour is undefined.
p
-----
The
.Fn pthread_cond_wait
function atomically blocks the current thread waiting on the condition
variable specified by
.Fa cond ,
and unlocks the mutex specified by
.Fa mutex .
The waiting thread unblocks after another thread calls
.Xr pthread_cond_signal 3 ,
or
.Xr pthread_cond_broadcast 3
with the same condition variable.
The current thread holds the lock on
.Fa mutex
upon return from the
.Fn pthread_cond_wait
call.
p The .Fn pthread_cond_timedwait function atomically blocks the current thread waiting on the condition variable specified by .Fa cond , and unlocks the mutex specified by .Fa mutex . The waiting thread unblocks after another thread calls .Xr pthread_cond_signal 3 , or .Xr pthread_cond_broadcast 3 with the same condition variable, or if the system time reaches the time specified in .Fa abstime , represented as .Em struct timespec (see .Xr timespec 3 ) .
p Note that a call to .Fn pthread_cond_wait or .Fn pthread_cond_timedwait may wake up spontaneously, without a call to .Xr pthread_cond_signal 3 or .Xr pthread_cond_broadcast 3 . The caller should prepare for this by invoking .Fn pthread_cond_wait or .Fn pthread_cond_timedwait within a predicate loop that tests whether the thread should proceed.
p When calling .Fn pthread_cond_wait or .Fn pthread_cond_timedwait , a temporary binding is established between the condition variable .Fa cond and the mutex .Fa mutex .
p
The same mutex must be held while calling
.Fn pthread_cond_broadcast
and
.Fn pthread_cond_signal
on
.Fa cond .
Additionally, the same mutex must be used for concurrent calls to
.Fn pthread_cond_wait
and
.Fn pthread_cond_timedwait .
Only when a condition variable is known to be quiescent may an application
change the mutex associated with it.
In this implementation, none of the functions enforce this requirement, but
if the mutex is not held or independent mutexes are used the resulting
behaviour is undefined.
----------------------------------------------------------------------------
.Sh RETURN VALUES
If successful, the
.Fn pthread_cond_init
function will return zero and put the new condition variable id into
.Fa cond ,
otherwise an error number will be returned to indicate the error.
p
-----
If successful, the
.Fn pthread_cond_destroy ,
.Fn pthread_cond_signal ,
.Fn pthread_cond_broadcast ,
.Fn pthread_cond_wait
and
.Fn pthread_cond_timedwait
will return zero, otherwise an error number will be returned to
indicate the error.
----------------------------------------------------------------------------
.Sh ERRORS
.Fn pthread_cond_init
may fail if:
l -tag -width Er t Bq Er EAGAIN The system lacks the resources to initialize another condition variable.
t Bq Er ENOMEM The process cannot allocate enough memory to initialize another condition
variable.
t Bq Er EINVAL The value specified by
.Fa attr
is invalid.
.El
p
-----
.Fn pthread_cond_destroy
may fail if:
l -tag -width Er t Bq Er EBUSY The variable
.Fa cond
is locked by another thread.
t Bq Er EINVAL The value specified by
.Fa cond
is invalid.
.El
p
-----
.Fn pthread_cond_broadcast
and
.Fn pthread_cond_signal
may fail if:
l -tag -width Er t Bq Er EINVAL The value specified by
.Fa cond
is invalid.
.El
p
-----
.Fn pthread_cond_wait
may fail if:
l -tag -width Er t Bq Er EINVAL The value specified by
.Fa cond
or the value specified by
.Fa mutex
is invalid.
.El
p .Fn pthread_cond_timedwait may fail if: l -tag -width Er t Bq Er ETIMEDOUT The system time has reached or exceeded the time specified in .Fa abstime . t Bq Er EINVAL The value specified by .Fa cond , .Fa mutex , or .Fa abstime is invalid. .El
p
.Fn pthread_cond_wait
and
.Fn pthread_cond_timedwait
may fail if:
l -tag -width Er t Bq Er EPERM The value specified by
.Fa mutex
is not locked in condition wait.
.El
----------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pthread 3 ,
.Xr pthread_barrier 3 ,
.Xr pthread_condattr 3 ,
.Xr pthread_mutex 3 ,
.Xr pthread_rwlock 3 ,
.Xr pthread_spin 3
.Sh STANDARDS
These functions conform to
.St -p1003.1-2001 .