282 lines
8.9 KiB
Groff
282 lines
8.9 KiB
Groff
.\" $NetBSD: pthread_cond.3,v 1.9 2018/07/28 14:00:19 kre Exp $
|
|
.\"
|
|
.\" 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 ,
|
|
.Nm pthread_cond_init ,
|
|
.Nm pthread_cond_destroy ,
|
|
.Nm pthread_cond_broadcast ,
|
|
.Nm pthread_cond_signal ,
|
|
.Nm pthread_cond_wait ,
|
|
.Nm pthread_cond_timedwait
|
|
.Nd condition variable interface
|
|
.Sh LIBRARY
|
|
.Lb libpthread
|
|
.\" ----------------------------------------------------------------------------
|
|
.Sh SYNOPSIS
|
|
.In pthread.h
|
|
.Ft int
|
|
.Fn pthread_cond_init "pthread_cond_t * restrict cond" \
|
|
"const pthread_condattr_t * restrict attr"
|
|
.Vt pthread_cond_t cond No = 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
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fn pthread_cond_init
|
|
function creates a new condition variable, with attributes specified with
|
|
.Fa attr .
|
|
If
|
|
.Fa attr
|
|
is
|
|
.Dv NULL
|
|
the default attributes are used.
|
|
The
|
|
.Fn pthread_cond_destroy
|
|
function frees the resources allocated by the condition variable
|
|
.Fa cond .
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.\" -----
|
|
The difference between
|
|
.Fn pthread_cond_broadcast
|
|
and
|
|
.Fn pthread_cond_signal
|
|
is that the former unblocks all threads waiting for the condition variable,
|
|
whereas the latter unblocks only one waiting thread.
|
|
If no threads are waiting on
|
|
.Fa cond ,
|
|
neither function has any effect.
|
|
If more than one thread is blocked on a condition variable,
|
|
the used scheduling policy determines the order in which threads are unblocked.
|
|
The same mutex used for waiting must be held while calling either function.
|
|
Although neither function strictly enforces this requirement,
|
|
undefined behavior may follow if the mutex is not held.
|
|
.Pp
|
|
.\" -----
|
|
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
|
|
.Fn pthread_cond_timedwait
|
|
function behaves similarly, but unblocks also
|
|
if the system time reaches the time specified in
|
|
.Fa abstime ,
|
|
represented as
|
|
.Em struct timespec
|
|
(see
|
|
.Xr timespec 3 ) .
|
|
With both functions the waiting thread unblocks after another thread calls
|
|
.Fn pthread_cond_signal
|
|
or
|
|
.Fn pthread_cond_broadcast
|
|
with the same condition variable and by holding the same
|
|
.Fa mutex
|
|
that was associated with
|
|
.Fa cond
|
|
by either one of the blocking functions.
|
|
The current thread holds the lock on
|
|
.Fa mutex
|
|
upon return from either function.
|
|
.\" -----
|
|
.Pp
|
|
Note that a call to
|
|
.Fn pthread_cond_wait
|
|
or
|
|
.Fn pthread_cond_timedwait
|
|
may wake up spontaneously, without a call to
|
|
.Fn pthread_cond_signal
|
|
or
|
|
.Fn pthread_cond_broadcast .
|
|
The caller should prepare for this by invoking either function
|
|
within a predicate loop that tests whether the thread should proceed.
|
|
.Pp
|
|
.\" -----
|
|
As noted, when calling either function that waits on a condition variable,
|
|
a temporary binding is established between the condition variable
|
|
.Fa cond
|
|
and the mutex
|
|
.Fa mutex .
|
|
During this time, the effect of an attempt by any thread to wait on
|
|
that condition variable using a different mutex is undefined.
|
|
The same mutex must be held while broadcasting or signaling 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, all functions return zero.
|
|
Otherwise, an error number will be returned to indicate the error.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn pthread_cond_init
|
|
function may fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The value specified by
|
|
.Fa attr
|
|
is invalid.
|
|
.El
|
|
.Pp
|
|
.\" -----
|
|
The
|
|
.Fn pthread_cond_destroy
|
|
function may fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBUSY
|
|
The variable
|
|
.Fa cond
|
|
is locked by another thread.
|
|
.It Bq Er EINVAL
|
|
The value specified by
|
|
.Fa cond
|
|
is invalid.
|
|
.El
|
|
.Pp
|
|
.\" -----
|
|
Both
|
|
.Fn pthread_cond_broadcast
|
|
and
|
|
.Fn pthread_cond_signal
|
|
may fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The value specified by
|
|
.Fa cond
|
|
is invalid.
|
|
.El
|
|
.Pp
|
|
.\" -----
|
|
Both
|
|
.Fn pthread_cond_wait
|
|
and
|
|
.Fn pthread_cond_timedwait
|
|
may fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The value specified by
|
|
.Fa cond
|
|
or the value specified by
|
|
.Fa mutex
|
|
is invalid.
|
|
.It Bq Er EPERM
|
|
The value specified by
|
|
.Fa mutex
|
|
was not locked in the condition wait.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn pthread_cond_timedwait
|
|
function may additionally fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ETIMEDOUT
|
|
The system time has reached or exceeded the time specified in
|
|
.Fa abstime .
|
|
.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 .
|