xref: /illumos-gate/usr/src/man/man3c/pthread_cond_wait.3c (revision 10d41d991988b6dfe2f102d139fb64152e1614ce)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd June 23, 2024
.Dt PTHREAD_COND_WAIT 3C
.Os
.Sh NAME
.Nm pthread_cond_wait ,
.Nm pthread_cond_clockwait ,
.Nm pthread_cond_timedwait ,
.Nm pthread_cond_relclockwait_np ,
.Nm pthread_cond_reltimedwait_np
.Nd wait on a condition
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.Ft int
.Fo pthread_cond_wait
.Fa "pthread_cond_t *restrict cond"
.Fa "pthread_mutex_t *restrict mutex"
.Fc
.Ft int
.Fo pthread_cond_clockwait
.Fa "pthread_cond_t *restrict cond"
.Fa "pthread_mutex_t *restrict mutex"
.Fa "clockid_t clock"
.Fa "const struct timespec *restrict abstime"
.Fc
.Ft int
.Fo pthread_cond_timedwait
.Fa "pthread_cond_t *restrict cond"
.Fa "pthread_mutex_t *restrict mutex"
.Fa "const struct timespec *restrict abstime"
.Fc
.Ft int
.Fo pthread_cond_relclockwait_np
.Fa "pthread_cond_t *restrict cond"
.Fa "pthread_mutex_t *restrict mutex"
.Fa "clockid_t clock"
.Fa "const struct timespec *restrict reltime"
.Fc
.Ft int
.Fo pthread_cond_reltimedwait_np
.Fa "pthread_cond_t *restrict cond"
.Fa "pthread_mutex_t *restrict mutex"
.Fa "const struct timespec *restrict reltime"
.Fc
.Sh DESCRIPTION
The
.Fn pthread_cond_wait ,
.Fn pthread_cond_clockwait ,
.Fn pthread_cond_timedwait ,
.Fn pthread_cond_relclockwait_np ,
and
.Fn pthread_cond_reltimedwait_np
functions are used to block on a condition variable.
They must be called with
.Fa mutex
locked by the calling thread or undefined behavior will result.
.Pp
These functions atomically release
.Fa mutex
and cause the calling thread to block on the condition variable
.Fa cond .
Atomically here means atomically with respect to access by another thread to
the mutex and then the condition variable.
That is, if another thread is able to acquire the mutex after the about-to-block
thread has released it, then a subsequent call to
.Xr pthread_cond_signal 3C
or
.Xr pthread_cond_broadcast 3C
in that thread behaves as if it were issued after the about-to-block thread has
blocked.
.Pp
Upon successful return, the mutex has been locked and is owned by the calling
thread.
If mutex is a robust mutex where an owner terminated while holding the lock and
the state is recoverable, the mutex is acquired even though the function returns
an error value.
.Pp
When using condition variables there is always a boolean predicate, an
invariant, associated with each condition wait that must be true before the
thread should proceed.
Spurious wakeups from the
.Fn pthread_cond_wait ,
.Fn pthread_cond_clockwait ,
.Fn pthread_cond_timedwait ,
.Fn pthread_cond_relclockwait_np ,
or
.Fn pthread_cond_reltimedwait_np
functions could occur.
The return from these functions does not imply anything about the value of this
predicate and the predicate must always be reevaluated.
.Pp
The order in which blocked threads are awakened by
.Xr pthread_cond_signal 3C
or
.Xr pthread_cond_broadcast 3C
is determined by the scheduling policy.
See
.Xr pthreads 7 .
.Pp
The effect of using more than one mutex for concurrent
.Fn pthread_cond_wait ,
.Fn pthread_cond_clockwait ,
.Fn pthread_cond_timedwait ,
.Fn pthread_cond_relclockwait_np ,
or
.Fn pthread_cond_reltimedwait_np
operations on the same condition variable will result in undefined behavior.
.Pp
A condition wait
.Pq whether timed or not
is a cancellation point.
When the cancelability enable state of a thread is set to
.Dv PTHREAD_CANCEL_DEFERRED ,
a side effect of acting upon a cancellation request while in a condition wait
is that the mutex is reacquired before calling the first cancellation cleanup
handler.
.Pp
A thread that has been unblocked because it has been canceled while blocked in
a call to any of these functions does not consume any condition signal that may
be directed concurrently at the condition variable if there are other threads
blocked on the condition variable.
.Pp
The
.Fn pthread_cond_wait
function will block forever until it is signaled.
With the other functions, it is possible to bound the amount of time that the
calling thread will block waiting to be signaled.
When a timeout occurs, the calling threads will return with the mutex held, but
will instead indicate an error occurred.
.Pp
In general, the system provides the ability to program timeouts against
either the realtime clock,
.Dv CLOCK_REALTIME ,
which measures the wall clock and is subject to changes due to time
synchronization daemons such as NTP and PTP, or the high-resolution clock,
.Dv CLOCK_HIGHRES ,
which is a non-adjustable high-resolution clock that is provided by
system hardware.
The specified timeout may either be specified as an absolute time in the
future or as a relative amount of time that should elapse.
Each clock has its own resolution, which can be determined by
.Xr clock_getres 3C .
Timeouts may be rounded up to a given clock's resolution.
.Pp
The
.Fn pthread_cond_timedwait
and
.Fn pthrad_cond_reltimedwait_np
functions determine which clock they use to wait based upon the clock that the
condition variable was created with.
By default, all timed condition variables utilize the realtime clock,
.Dv CLOCK_REALTIME .
The default clock may be changed on a per-condition variable basis by setting
the condition variable's attributes with the
.Xr pthread_condattr_setclock 3C
function when creating the condition variable.
.Pp
The
.Fn pthread_cond_clockwait
and
.Fn pthread_cond_relclockwait_np
functions ignore the condition variable's defined clock and instead utilize the
clock specified by the
.Fa clock
argument.
While there are additional clocks in the system, only
.Dv CLOCK_REALTIME
or
.Dv CLOCK_HIGHRES
may be specified.
The thread and process-specific CPU time clocks cannot be used.
.Pp
The
.Fn pthread_cond_clockwait
and
.Fn pthread_cond_timedwait
functions treat the timeout value,
.Fa abstime ,
as the absolute time in the future when the timeout should expire.
Conversely, the
.Fn pthread_cond_relclockwait_np
and
.Fn pthread_cond_reltimedwait_np
functions operate in terms of a relative time.
The timer will expire when a specified amount of time passes on the
clock as indicated by
.Fa reltime .
.Pp
The
.Fn pthread_cond_wait ,
.Fn pthread_cond_clockwait ,
.Fn pthread_cond_timedwait ,
.Fn pthread_cond_relclockwait_np ,
or
.Fn pthread_cond_reltimedwait_np
functions split the errors that they return into those that occur before and
those that occur after dropping the lock in any form.
In particular, error checking is guaranteed to occur before releasing the mutex
and waiting on the condition variable.
The errors
.Er ETIMEDOUT ,
.Er EOWNERDEAD ,
and
.Er ENOTRECOVERABLE
are the only errors that may occur after a wait has begun.
The latter two errors only apply to a robust mutex.
No matter why the calling functions return, they will always return with the
mutex
.Fa mutex
held, excepting certain unrecoverable robust mutexes.
In addition, if the calling thread that is waiting on a condition variable
takes a signal, the thread will never return
.Er EINTR .
It may resume blocking or potentially deliver a spurious wakeup.
.Sh RETURN VALUES
Upon successful completion, the
.Fn pthread_cond_wait ,
.Fn pthread_cond_clockwait ,
.Fn pthread_cond_timedwait ,
.Fn pthread_cond_relclockwait_np ,
and
.Fn pthread_cond_reltimedwait_np
functions return 0.
Otherwise, an error value is returned to indicate the error.
.Sh ERRORS
The
.Fn pthread_cond_wait ,
.Fn pthread_cond_clockwait ,
.Fn pthread_cond_timedwait ,
.Fn pthread_cond_relclockwait_np ,
and
.Fn pthread_cond_reltimedwait_np
functions will fail if:
.Bl -tag -width Er
.It Er EPERM
The mutex type is
.Dv PTHREAD_MUTEX_ERRORCHECK
or the mutex is a robust mutex, and the current thread does not own the mutex.
.It Er ETIMEDOUT
The absolute or relative time specified by
.Fa abstime
and
.Fa reltime
respectively, has passed.
This does not apply to
.Fn pthread_cond_wait .
.It Er EINVAL
One or more of the values specified by
.Fa cond ,
.Fa mutex ,
.Fa abstime ,
or
.Fa reltime
is invalid.
.Pp
Different mutexes were supplied for concurrent operation on the same condition
variable.
.Pp
The value of
.Fa clock
is either unsupported for timing operations or the value is unknown to the
system.
.It Er EOWNERDEAD
The mutex is a robust mutex initialized with the attribute
.Dv PTHREAD_MUTEX_ROBUST
and the last owner of this mutex died while holding the mutex, leaving the
state it was protecting possibly inconsistent.
The mutex is now owned by the caller.
.It Er ENOTRECOVERABLE
The mutex is a robust mutex initialized with the attribute
.Dv PTHREAD_MUTEX_ROBUST
and the mutex was protecting state that has now been left irrecoverable.
The mutex has not been acquired.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr clock_getres 3C ,
.Xr pthread_cond_broadcast 3C ,
.Xr pthread_cond_signal 3C ,
.Xr pthread_condattr_setclock 3C ,
.Xr pthread_mutex_lock 3C ,
.Xr pthread_mutexattr_getrobust 3C ,
.Xr time.h 3HEAD ,
.Xr attributes 7 ,
.Xr condition 7 ,
.Xr pthreads 7 ,
.Xr standards 7