path: root/usr/src/man/man9f/condvar.9f

'\" te
.\"  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
.\"  Copyright 2016 Joyent, Inc.
.\" 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]
.TH CONDVAR 9F "Mar 29, 2016"
.SH NAME
condvar, cv_init, cv_destroy, cv_wait, cv_signal, cv_broadcast, cv_wait_sig,
cv_timedwait, cv_timedwait_sig \- condition variable routines
.SH SYNOPSIS
.nf
#include <sys/ksynch.h>



\fBvoid\fR \fBcv_init\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBchar *\fR\fIname\fR, \fBkcv_type_t\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcv_destroy\fR(\fBkcondvar_t *\fR\fIcvp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcv_wait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcv_signal\fR(\fBkcondvar_t *\fR\fIcvp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBcv_broadcast\fR(\fBkcondvar_t *\fR\fIcvp\fR);
.fi

.LP
.nf
\fBint\fR \fBcv_wait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR);
.fi

.LP
.nf
\fBclock_t\fR \fBcv_timedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR);
.fi

.LP
.nf
\fBclock_t\fR \fBcv_timedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR);
.fi

.LP
.nf
\fBclock_t\fR \fBcv_reltimedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fIdelta\fR,
    \fBtime_res_t\fR \fIres\fR);
.fi

.LP
.nf
\fBclock_t\fR \fBcv_reltimedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fIdelta\fR,
    \fBtime_res_t\fR \fIres\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fIcvp\fR\fR
.ad
.RS 11n
A pointer to an abstract data type \fBkcondvar_t\fR.
.RE

.sp
.ne 2
.na
\fB\fImp\fR\fR
.ad
.RS 11n
A pointer to a mutual exclusion lock (\fBkmutex_t\fR), initialized by
\fBmutex_init\fR(9F) and held by the caller.
.RE

.sp
.ne 2
.na
\fB\fIname\fR\fR
.ad
.RS 11n
Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR
strings are legal, but they're a waste of kernel memory.)
.RE

.sp
.ne 2
.na
\fB\fItype\fR\fR
.ad
.RS 11n
The constant \fBCV_DRIVER\fR.
.RE

.sp
.ne 2
.na
\fB\fIarg\fR\fR
.ad
.RS 11n
A type-specific argument, drivers should pass arg as \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fItimeout\fR\fR
.ad
.RS 11n
A time, in absolute ticks since boot, when \fBcv_timedwait()\fR or
\fBcv_timedwait_sig()\fR should return.
.RE

.sp
.ne 2
.na
\fB\fIdelta\fR\fR
.ad
.RS 11n
A time, in ticks, to indicate how long \fBcv_reltimedwait()\fR or
\fBcv_reltimedwait_sig()\fR should wait before returning. Drivers should use
\fBdrv_usectohz\fR(9F) to determine this value.
.RE

.sp
.ne 2
.na
\fB\fIres\fR\fR
.ad
.RS 11n
A value which describes the requested accuracy of the timeout argument.
The system may anticipate or defer the timeout based on the requested
accuracy to prevent unnecessary wakeups. The following identifiers are
valid arguments for this type:
.LP
.RS 4n
.B TR_NANOSEC
.RS 16n
Nanosecond granularity
.RE
.RE
.RS 4n
.B TR_MICROSEC
.RS 16n
Microsecond granularity
.RE
.RE
.RS 4n
.B TR_MILLISEC
.RS 16n
Millisecond granularity
.RE
.RE
.RS 4n
.B TR_SEC
.RS 16n
Second granularity
.RE
.RE
.RS 4n
.B TR_CLOCK_TICK
.RS 16n
Granularity of a kernel clock tick, commonly 100 or 1000 Hz.
.RE
.RE
.LP
Note that the granularity of these functions is in clock ticks,
therefore the only values which will have an effect are:
.B TR_SEC
and
.B TR_CLOCK_TICK .
.RE

.SH DESCRIPTION
Condition variables are a standard form of thread synchronization. They are
designed to be used with mutual exclusion locks (mutexes). The associated mutex
is used to ensure that a condition can be checked atomically and that the
thread can block on the associated condition variable without missing either a
change to the condition or a signal that the condition has changed. Condition
variables must be initialized by calling \fBcv_init()\fR, and must be
deallocated by calling \fBcv_destroy()\fR.
.sp
.LP
The usual use of condition variables is to check a condition (for example,
device state, data structure reference count, etc.) while holding a mutex which
keeps other threads from changing the condition. If the condition is such that
the thread should block, \fBcv_wait()\fR is called with a related condition
variable and the mutex. At some later point in time, another thread would
acquire the mutex, set the condition such that the previous thread can be
unblocked, unblock the previous thread with \fBcv_signal()\fR or
\fBcv_broadcast()\fR, and then release the mutex.
.sp
.LP
\fBcv_wait()\fR suspends the calling thread and exits the mutex atomically so
that another thread which holds the mutex cannot signal on the condition
variable until the blocking thread is blocked. Before returning, the mutex is
reacquired.
.sp
.LP
\fBcv_signal()\fR signals the condition and wakes one blocked thread. All
blocked threads can be unblocked by calling \fBcv_broadcast()\fR.
\fBcv_signal()\fR and \fBcv_broadcast()\fR can be called by a thread even if it
does not hold the mutex passed into \fBcv_wait()\fR, though holding the mutex
is necessary to ensure predictable scheduling.
.sp
.LP
The function \fBcv_wait_sig()\fR is similar to \fBcv_wait()\fR but returns
\fB0\fR if a signal (for example, by \fBkill\fR(2)) is sent to the thread. In
any case, the mutex is reacquired before returning.
.sp
.LP
The function \fBcv_timedwait()\fR is similar to \fBcv_wait()\fR, except that it
returns \fB\(mi1\fR without the condition being signaled after the timeout time
has been reached.
.sp
.LP
The function \fBcv_timedwait_sig()\fR is similar to \fBcv_timedwait()\fR and
\fBcv_wait_sig()\fR, except that it returns \fB\(mi1\fR without the condition
being signaled after the timeout time has been reached, or \fB0\fR if a signal
(for example, by \fBkill\fR(2)) is sent to the thread.
.sp
.LP
For both \fBcv_timedwait()\fR and \fBcv_timedwait_sig()\fR, time is in absolute
clock ticks since the last system reboot. The current time may be found by
calling \fBddi_get_lbolt\fR(9F).
.sp
.LP
The functions
.B cv_reltimedwait()
and
.B cv_reltimedwait_sig()
behave similarly to
.B cv_timedwait() and
.B cv_timedwait_sig()
respectively, except instead of taking a time in absolute clock ticks,
they take a relative number of clock ticks to wait. In addition, both
functions take an additional argument
.I res,
which specifies the desired granularity that the system should default
to, generally the value
.B TR_CLOCK_TICK .
.SH RETURN VALUES
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 9n
For \fBcv_wait_sig()\fR, \fBcv_timedwait_sig()\fR, and
\fBcv_reltimedwait_sig()\fR indicates that the condition was not necessarily
signaled and the function returned because a signal (as in \fBkill\fR(2)) was
pending.
.RE

.sp
.ne 2
.na
\fB\fB\(mi1\fR\fR
.ad
.RS 9n
For \fBcv_timedwait()\fR, \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
\fBcv_reltimedwait_sig()\fR, indicates that the condition was not necessarily
signaled and the function returned because the timeout time was reached.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 9n
For \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR, \fBcv_timedwait_sig()\fR,
\fBcv_reltimedwait()\fR, and \fBcv_reltimedwait_sig()\fR, indicates that the
condition was met and the function returned due to a call to \fBcv_signal()\fR
or \fBcv_broadcast()\fR, or due to a premature wakeup (see NOTES).
.RE

.SH CONTEXT
These functions can be called from user, kernel or interrupt context. In most
cases, however, \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR,
\fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
\fBcv_reltimedwait_sig()\fR, should not be called from interrupt context, and
cannot be called from a high-level interrupt context.
.sp
.LP
If \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR,
\fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, or
\fBcv_reltimedwait_sig()\fR, are used from interrupt context, lower-priority
interrupts will not be serviced during the wait. This means that if the thread
that will eventually perform the wakeup becomes blocked on anything that
requires the lower-priority interrupt, the system will hang.
.sp
.LP
For example, the thread that will perform the wakeup may need to first allocate
memory. This memory allocation may require waiting for paging \fBI/O\fR to
complete, which may require a lower-priority disk or network interrupt to be
serviced. In general, situations like this are hard to predict, so it is
advisable to avoid waiting on condition variables or semaphores in an interrupt
context.
.SH EXAMPLES
\fBExample 1 \fRWaiting for a Flag Value in a Driver's Unit
.sp
.LP
Here the condition being waited for is a flag value in a driver's unit
structure. The condition variable is also in the unit structure, and the flag
word is protected by a mutex in the unit structure.

.sp
.in +2
.nf
	mutex_enter(&un->un_lock);
	while (un->un_flag & UNIT_BUSY)
       cv_wait(&un->un_cv, &un->un_lock);
	un->un_flag |= UNIT_BUSY;
	mutex_exit(&un->un_lock);
.fi
.in -2

.LP
\fBExample 2 \fRUnblocking Threads Blocked by the Code in Example 1
.sp
.LP
At some later point in time, another thread would execute the following to
unblock any threads blocked by the above code.

.sp
.in +2
.nf

mutex_enter(&un->un_lock);
un->un_flag &= ~UNIT_BUSY;
cv_broadcast(&un->un_cv);
mutex_exit(&un->un_lock);
.fi
.in -2

.SH NOTES
It is possible for \fBcv_wait()\fR, \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR,
\fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
\fBcv_reltimedwait_sig()\fR to return prematurely, that is, not due to a call to
\fBcv_signal()\fR or \fBcv_broadcast()\fR. This occurs most commonly in the case
of \fBcv_wait_sig()\fR and \fBcv_timedwait_sig()\fR when the thread is stopped
and restarted by job control signals or by a debugger, but can happen in other
cases as well, even for \fBcv_wait()\fR. Code that calls these functions must
always recheck the reason for blocking and call again if the reason for blocking
is still true.
.sp
.LP
If your driver needs to wait on behalf of processes that have real-time
constraints, use \fBcv_timedwait()\fR rather than \fBdelay\fR(9F). The
\fBdelay()\fR function calls \fBtimeout\fR(9F), which can be subject to
priority inversions.
.sp
.LP
Not all threads can receive signals from user level processes. In cases where
such reception is impossible (such as during execution of \fBclose\fR(9E) due
to \fBexit\fR(2)), \fBcv_wait_sig()\fR behaves as \fBcv_wait()\fR,
\fBcv_timedwait_sig()\fR behaves as \fBcv_timedwait()\fR, and
\fBcv_reltimedwait_sig()\fR behaves as \fBcv_reltimedwait()\fR. To avoid unkillable
processes, users of these functions may need to protect against waiting
indefinitely for events that might not occur. The \fBddi_can_receive_sig\fR(9F)
function is provided to detect when signal reception is possible.
.SH SEE ALSO
\fBkill\fR(2), \fBddi_can_receive_sig\fR(9F), \fBddi_get_lbolt\fR(9F),
\fBdrv_usectohz\fR(9F) \fBmutex\fR(9F), \fBmutex_init\fR(9F),
.sp
.LP
\fIWriting Device Drivers\fR