share/man/man9f/condvar.9f

   1 '\" te
   2 .\"  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   3 .\"  Copyright 2016 Joyent, Inc.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH CONDVAR 9F "Mar 29, 2016"
   8 .SH NAME
   9 condvar, cv_init, cv_destroy, cv_wait, cv_signal, cv_broadcast, cv_wait_sig,
  10 cv_timedwait, cv_timedwait_sig, cv_reltimedwait, cv_reltimedwait_sig \-
  11 condition variable routines
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 #include <sys/ksynch.h>
  16
  17
  18
  19 \fBvoid\fR \fBcv_init\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBchar *\fR\fIname\fR, \fBkcv_type_t\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBvoid\fR \fBcv_destroy\fR(\fBkcondvar_t *\fR\fIcvp\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBcv_wait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBvoid\fR \fBcv_signal\fR(\fBkcondvar_t *\fR\fIcvp\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBvoid\fR \fBcv_broadcast\fR(\fBkcondvar_t *\fR\fIcvp\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBint\fR \fBcv_wait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBclock_t\fR \fBcv_timedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBclock_t\fR \fBcv_timedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBclock_t\fR \fBcv_reltimedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fIdelta\fR,
  60     \fBtime_res_t\fR \fIres\fR);
  61 .fi
  62
  63 .LP
  64 .nf
  65 \fBclock_t\fR \fBcv_reltimedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fIdelta\fR,
  66     \fBtime_res_t\fR \fIres\fR);
  67 .fi
  68
  69 .SH INTERFACE LEVEL
  70 .LP
  71 Solaris DDI specific (Solaris DDI).
  72 .SH PARAMETERS
  73 .ne 2
  74 .na
  75 \fB\fIcvp\fR\fR
  76 .ad
  77 .RS 11n
  78 A pointer to an abstract data type \fBkcondvar_t\fR.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fImp\fR\fR
  85 .ad
  86 .RS 11n
  87 A pointer to a mutual exclusion lock (\fBkmutex_t\fR), initialized by
  88 \fBmutex_init\fR(9F) and held by the caller.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIname\fR\fR
  95 .ad
  96 .RS 11n
  97 Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR
  98 strings are legal, but they're a waste of kernel memory.)
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fItype\fR\fR
 105 .ad
 106 .RS 11n
 107 The constant \fBCV_DRIVER\fR.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fIarg\fR\fR
 114 .ad
 115 .RS 11n
 116 A type-specific argument, drivers should pass arg as \fINULL\fR.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fItimeout\fR\fR
 123 .ad
 124 .RS 11n
 125 A time, in absolute ticks since boot, when \fBcv_timedwait()\fR or
 126 \fBcv_timedwait_sig()\fR should return.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fIdelta\fR\fR
 133 .ad
 134 .RS 11n
 135 A time, in ticks, to indicate how long \fBcv_reltimedwait()\fR or
 136 \fBcv_reltimedwait_sig()\fR should wait before returning. Drivers should use
 137 \fBdrv_usectohz\fR(9F) to determine this value.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fIres\fR\fR
 144 .ad
 145 .RS 11n
 146 A value which describes the requested accuracy of the timeout argument.
 147 The system may anticipate or defer the timeout based on the requested
 148 accuracy to prevent unnecessary wakeups. The following identifiers are
 149 valid arguments for this type:
 150 .LP
 151 .RS 4n
 152 .B TR_NANOSEC
 153 .RS 16n
 154 Nanosecond granularity
 155 .RE
 156 .RE
 157 .RS 4n
 158 .B TR_MICROSEC
 159 .RS 16n
 160 Microsecond granularity
 161 .RE
 162 .RE
 163 .RS 4n
 164 .B TR_MILLISEC
 165 .RS 16n
 166 Millisecond granularity
 167 .RE
 168 .RE
 169 .RS 4n
 170 .B TR_SEC
 171 .RS 16n
 172 Second granularity
 173 .RE
 174 .RE
 175 .RS 4n
 176 .B TR_CLOCK_TICK
 177 .RS 16n
 178 Granularity of a kernel clock tick, commonly 100 or 1000 Hz.
 179 .RE
 180 .RE
 181 .LP
 182 Note that the granularity of these functions is in clock ticks,
 183 therefore the only values which will have an effect are:
 184 .B TR_SEC
 185 and
 186 .B TR_CLOCK_TICK .
 187 .RE
 188
 189 .SH DESCRIPTION
 190 .LP
 191 Condition variables are a standard form of thread synchronization. They are
 192 designed to be used with mutual exclusion locks (mutexes). The associated mutex
 193 is used to ensure that a condition can be checked atomically and that the
 194 thread can block on the associated condition variable without missing either a
 195 change to the condition or a signal that the condition has changed. Condition
 196 variables must be initialized by calling \fBcv_init()\fR, and must be
 197 deallocated by calling \fBcv_destroy()\fR.
 198 .sp
 199 .LP
 200 The usual use of condition variables is to check a condition (for example,
 201 device state, data structure reference count, etc.) while holding a mutex which
 202 keeps other threads from changing the condition. If the condition is such that
 203 the thread should block, \fBcv_wait()\fR is called with a related condition
 204 variable and the mutex. At some later point in time, another thread would
 205 acquire the mutex, set the condition such that the previous thread can be
 206 unblocked, unblock the previous thread with \fBcv_signal()\fR or
 207 \fBcv_broadcast()\fR, and then release the mutex.
 208 .sp
 209 .LP
 210 \fBcv_wait()\fR suspends the calling thread and exits the mutex atomically so
 211 that another thread which holds the mutex cannot signal on the condition
 212 variable until the blocking thread is blocked. Before returning, the mutex is
 213 reacquired.
 214 .sp
 215 .LP
 216 \fBcv_signal()\fR signals the condition and wakes one blocked thread. All
 217 blocked threads can be unblocked by calling \fBcv_broadcast()\fR.
 218 \fBcv_signal()\fR and \fBcv_broadcast()\fR can be called by a thread even if it
 219 does not hold the mutex passed into \fBcv_wait()\fR, though holding the mutex
 220 is necessary to ensure predictable scheduling.
 221 .sp
 222 .LP
 223 The function \fBcv_wait_sig()\fR is similar to \fBcv_wait()\fR but returns
 224 \fB0\fR if a signal (for example, by \fBkill\fR(2)) is sent to the thread. In
 225 any case, the mutex is reacquired before returning.
 226 .sp
 227 .LP
 228 The function \fBcv_timedwait()\fR is similar to \fBcv_wait()\fR, except that it
 229 returns \fB\(mi1\fR without the condition being signaled after the timeout time
 230 has been reached.
 231 .sp
 232 .LP
 233 The function \fBcv_timedwait_sig()\fR is similar to \fBcv_timedwait()\fR and
 234 \fBcv_wait_sig()\fR, except that it returns \fB\(mi1\fR without the condition
 235 being signaled after the timeout time has been reached, or \fB0\fR if a signal
 236 (for example, by \fBkill\fR(2)) is sent to the thread.
 237 .sp
 238 .LP
 239 For both \fBcv_timedwait()\fR and \fBcv_timedwait_sig()\fR, time is in absolute
 240 clock ticks since the last system reboot. The current time may be found by
 241 calling \fBddi_get_lbolt\fR(9F).
 242 .sp
 243 .LP
 244 The functions
 245 .B cv_reltimedwait()
 246 and
 247 .B cv_reltimedwait_sig()
 248 behave similarly to
 249 .B cv_timedwait() and
 250 .B cv_timedwait_sig()
 251 respectively, except instead of taking a time in absolute clock ticks,
 252 they take a relative number of clock ticks to wait. In addition, both
 253 functions take an additional argument
 254 .I res,
 255 which specifies the desired granularity that the system should default
 256 to, generally the value
 257 .B TR_CLOCK_TICK .
 258 .SH RETURN VALUES
 259 .ne 2
 260 .na
 261 \fB\fB0\fR\fR
 262 .ad
 263 .RS 9n
 264 For \fBcv_wait_sig()\fR, \fBcv_timedwait_sig()\fR, and
 265 \fBcv_reltimedwait_sig()\fR indicates that the condition was not necessarily
 266 signaled and the function returned because a signal (as in \fBkill\fR(2)) was
 267 pending.
 268 .RE
 269
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fB\(mi1\fR\fR
 274 .ad
 275 .RS 9n
 276 For \fBcv_timedwait()\fR, \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
 277 \fBcv_reltimedwait_sig()\fR, indicates that the condition was not necessarily
 278 signaled and the function returned because the timeout time was reached.
 279 .RE
 280
 281 .sp
 282 .ne 2
 283 .na
 284 \fB\fB>0\fR\fR
 285 .ad
 286 .RS 9n
 287 For \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR, \fBcv_timedwait_sig()\fR,
 288 \fBcv_reltimedwait()\fR, and \fBcv_reltimedwait_sig()\fR, indicates that the
 289 condition was met and the function returned due to a call to \fBcv_signal()\fR
 290 or \fBcv_broadcast()\fR, or due to a premature wakeup (see NOTES).
 291 .RE
 292
 293 .SH CONTEXT
 294 .LP
 295 These functions can be called from user, kernel or interrupt context. In most
 296 cases, however, \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR,
 297 \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
 298 \fBcv_reltimedwait_sig()\fR, should not be called from interrupt context, and
 299 cannot be called from a high-level interrupt context.
 300 .sp
 301 .LP
 302 If \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR,
 303 \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, or
 304 \fBcv_reltimedwait_sig()\fR, are used from interrupt context, lower-priority
 305 interrupts will not be serviced during the wait. This means that if the thread
 306 that will eventually perform the wakeup becomes blocked on anything that
 307 requires the lower-priority interrupt, the system will hang.
 308 .sp
 309 .LP
 310 For example, the thread that will perform the wakeup may need to first allocate
 311 memory. This memory allocation may require waiting for paging \fBI/O\fR to
 312 complete, which may require a lower-priority disk or network interrupt to be
 313 serviced. In general, situations like this are hard to predict, so it is
 314 advisable to avoid waiting on condition variables or semaphores in an interrupt
 315 context.
 316 .SH EXAMPLES
 317 .LP
 318 \fBExample 1 \fRWaiting for a Flag Value in a Driver's Unit
 319 .sp
 320 .LP
 321 Here the condition being waited for is a flag value in a driver's unit
 322 structure. The condition variable is also in the unit structure, and the flag
 323 word is protected by a mutex in the unit structure.
 324
 325 .sp
 326 .in +2
 327 .nf
 328         mutex_enter(&un->un_lock);
 329         while (un->un_flag & UNIT_BUSY)
 330        cv_wait(&un->un_cv, &un->un_lock);
 331         un->un_flag |= UNIT_BUSY;
 332         mutex_exit(&un->un_lock);
 333 .fi
 334 .in -2
 335
 336 .LP
 337 \fBExample 2 \fRUnblocking Threads Blocked by the Code in Example 1
 338 .sp
 339 .LP
 340 At some later point in time, another thread would execute the following to
 341 unblock any threads blocked by the above code.
 342
 343 .sp
 344 .in +2
 345 .nf
 346
 347 mutex_enter(&un->un_lock);
 348 un->un_flag &= ~UNIT_BUSY;
 349 cv_broadcast(&un->un_cv);
 350 mutex_exit(&un->un_lock);
 351 .fi
 352 .in -2
 353
 354 .SH NOTES
 355 .LP
 356 It is possible for \fBcv_wait()\fR, \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR,
 357 \fBcv_timedwait_sig()\fR, \fBcv_reltimedwait()\fR, and
 358 \fBcv_reltimedwait_sig()\fR to return prematurely, that is, not due to a call to
 359 \fBcv_signal()\fR or \fBcv_broadcast()\fR. This occurs most commonly in the case
 360 of \fBcv_wait_sig()\fR and \fBcv_timedwait_sig()\fR when the thread is stopped
 361 and restarted by job control signals or by a debugger, but can happen in other
 362 cases as well, even for \fBcv_wait()\fR. Code that calls these functions must
 363 always recheck the reason for blocking and call again if the reason for blocking
 364 is still true.
 365 .sp
 366 .LP
 367 If your driver needs to wait on behalf of processes that have real-time
 368 constraints, use \fBcv_timedwait()\fR rather than \fBdelay\fR(9F). The
 369 \fBdelay()\fR function calls \fBtimeout\fR(9F), which can be subject to
 370 priority inversions.
 371 .sp
 372 .LP
 373 Not all threads can receive signals from user level processes. In cases where
 374 such reception is impossible (such as during execution of \fBclose\fR(9E) due
 375 to \fBexit\fR(2)), \fBcv_wait_sig()\fR behaves as \fBcv_wait()\fR,
 376 \fBcv_timedwait_sig()\fR behaves as \fBcv_timedwait()\fR, and
 377 \fBcv_reltimedwait_sig()\fR behaves as \fBcv_reltimedwait()\fR. To avoid unkillable
 378 processes, users of these functions may need to protect against waiting
 379 indefinitely for events that might not occur. The \fBddi_can_receive_sig\fR(9F)
 380 function is provided to detect when signal reception is possible.
 381 .SH SEE ALSO
 382 .LP
 383 \fBkill\fR(2), \fBddi_can_receive_sig\fR(9F), \fBddi_get_lbolt\fR(9F),
 384 \fBdrv_usectohz\fR(9F) \fBmutex\fR(9F), \fBmutex_init\fR(9F),
 385 .sp
 386 .LP
 387 \fIWriting Device Drivers\fR