pthread yet again
This commit is contained in:
275
lib/libpthread/pthread_cond.3
Normal file
275
lib/libpthread/pthread_cond.3
Normal file
@@ -0,0 +1,275 @@
|
||||
.\" $NetBSD: pthread_cond.3,v 1.6 2012/11/12 23:11:05 uwe 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
|
||||
.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 blocks 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 .
|
||||
Reference in New Issue
Block a user