illumos: manual page: pthread_cond

PTHREAD_COND_WAIT(3C) Standard C Library Functions PTHREAD_COND_WAIT(3C)

NAME

pthread_cond_wait, pthread_cond_clockwait, pthread_cond_timedwait,
pthread_cond_relclockwait_np, pthread_cond_reltimedwait_np - wait on a
condition

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

int
pthread_cond_wait(pthread_cond_t *restrict cond,
pthread_mutex_t *restrict mutex);

int
pthread_cond_clockwait(pthread_cond_t *restrict cond,
pthread_mutex_t *restrict mutex, clockid_t clock,
const struct timespec *restrict abstime);

int
pthread_cond_timedwait(pthread_cond_t *restrict cond,
pthread_mutex_t *restrict mutex,
const struct timespec *restrict abstime);

int
pthread_cond_relclockwait_np(pthread_cond_t *restrict cond,
pthread_mutex_t *restrict mutex, clockid_t clock,
const struct timespec *restrict reltime);

int
pthread_cond_reltimedwait_np(pthread_cond_t *restrict cond,
pthread_mutex_t *restrict mutex,
const struct timespec *restrict reltime);

DESCRIPTION

The pthread_cond_wait(), pthread_cond_clockwait(),
pthread_cond_timedwait(), pthread_cond_relclockwait_np(), and
pthread_cond_reltimedwait_np() functions are used to block on a condition
variable. They must be called with mutex locked by the calling thread or
undefined behavior will result.

These functions atomically release mutex and cause the calling thread to
block on the condition variable 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 pthread_cond_signal(3C) or pthread_cond_broadcast(3C) in that
thread behaves as if it were issued after the about-to-block thread has
blocked.

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.

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 pthread_cond_wait(),
pthread_cond_clockwait(), pthread_cond_timedwait(),
pthread_cond_relclockwait_np(), or 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.

The order in which blocked threads are awakened by pthread_cond_signal(3C)
or pthread_cond_broadcast(3C) is determined by the scheduling policy. See
pthreads(7).

The effect of using more than one mutex for concurrent pthread_cond_wait(),
pthread_cond_clockwait(), pthread_cond_timedwait(),
pthread_cond_relclockwait_np(), or pthread_cond_reltimedwait_np()
operations on the same condition variable will result in undefined
behavior.

A condition wait (whether timed or not) is a cancellation point. When the
cancelability enable state of a thread is set to 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.

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.

The 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.

In general, the system provides the ability to program timeouts against
either the realtime clock, 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, 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 clock_getres(3C). Timeouts may be
rounded up to a given clock's resolution.

The pthread_cond_timedwait() and 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, CLOCK_REALTIME. The default clock
may be changed on a per-condition variable basis by setting the condition
variable's attributes with the pthread_condattr_setclock(3C) function when
creating the condition variable.

The pthread_cond_clockwait() and pthread_cond_relclockwait_np() functions
ignore the condition variable's defined clock and instead utilize the clock
specified by the clock argument. While there are additional clocks in the
system, only CLOCK_REALTIME or CLOCK_HIGHRES may be specified. The thread
and process-specific CPU time clocks cannot be used.

The pthread_cond_clockwait() and pthread_cond_timedwait() functions treat
the timeout value, abstime, as the absolute time in the future when the
timeout should expire. Conversely, the pthread_cond_relclockwait_np() and
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 reltime.

The pthread_cond_wait(), pthread_cond_clockwait(),
pthread_cond_timedwait(), pthread_cond_relclockwait_np(), or
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
ETIMEDOUT, EOWNERDEAD, and 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 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 EINTR. It may resume blocking
or potentially deliver a spurious wakeup.

RETURN VALUES

Upon successful completion, the pthread_cond_wait(),
pthread_cond_clockwait(), pthread_cond_timedwait(),
pthread_cond_relclockwait_np(), and pthread_cond_reltimedwait_np()
functions return 0. Otherwise, an error value is returned to indicate the
error.

ERRORS

The pthread_cond_wait(), pthread_cond_clockwait(),
pthread_cond_timedwait(), pthread_cond_relclockwait_np(), and
pthread_cond_reltimedwait_np() functions will fail if:

EPERM The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex
is a robust mutex, and the current thread does not own
the mutex.

ETIMEDOUT The absolute or relative time specified by abstime and
reltime respectively, has passed. This does not apply
to pthread_cond_wait().

EINVAL One or more of the values specified by cond, mutex,
abstime, or reltime is invalid.

Different mutexes were supplied for concurrent operation
on the same condition variable.

The value of clock is either unsupported for timing
operations or the value is unknown to the system.

EOWNERDEAD The mutex is a robust mutex initialized with the
attribute 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.

ENOTRECOVERABLE The mutex is a robust mutex initialized with the
attribute PTHREAD_MUTEX_ROBUST and the mutex was
protecting state that has now been left irrecoverable.
The mutex has not been acquired.

INTERFACE STABILITY

Committed

MT-LEVEL
MT-Safe