usr/src/man/man3c/cnd.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd "Jan 11, 2015"
  15 .Dt CND 3C
  16 .Os
  17 .Sh NAME
  18 .Nm cnd ,
  19 .Nm cnd_broadcast ,
  20 .Nm cnd_destroy ,
  21 .Nm cnd_init ,
  22 .Nm cnd_signal ,
  23 .Nm cnd_timedwait ,
  24 .Nm cnd_wait
  25 .Nd C11 condition variable functions
  26 .Sh SYNOPSIS
  27 .In threads.h
  28 .Ft int
  29 .Fo cnd_init
  30 .Fa "cnd_t *cnd"
  31 .Fc
  32 .Ft void
  33 .Fo cnd_destroy
  34 .Fa "cnd_t *cnd"
  35 .Fc
  36 .Ft int
  37 .Fo cnd_broadcast
  38 .Fa "cnd_t *cnd"
  39 .Fc
  40 .Ft int
  41 .Fo cnd_signal
  42 .Fa "cnd_t *cnd"
  43 .Fc
  44 .Ft int
  45 .Fo cnd_timedwait
  46 .Fa "cnd_t *restrict cnd"
  47 .Fa "mtx_t *restrict mtx"
  48 .Fa "const struct timespec *abstime"
  49 .Fc
  50 .Ft int
  51 .Fo cnd_wait
  52 .Fa "cnd_t *restrict cnd"
  53 .Fa "mtx_t *restrict mtx"
  54 .Fc
  55 .Sh DESCRIPTION
  56 The
  57 .Sy cnd
  58 family of functions implement condition variables which allow threads
  59 within a process to wait until a condition occurs and be signaled when
  60 it does.
  61 These functions behave similar to both the POSIX threads and illumos threads;
  62 however, they have slightly different call signatures and return values.
  63 For more information, see
  64 .Xr threads 5 .
  65 Importantly, they do not allow for inter-process synchronization.
  66 .Ss Creating and Destroy Condition Variables
  67 The function
  68 .Fn cnd_init
  69 initializes the condition variable referred to by
  70 .Fa cnd .
  71 The condition variable is suitable for intra-process use.
  72 Initializing an already initialized condition variable results in undefined
  73 behavior.
  74 .Pp
  75 The function
  76 .Fn cnd_destroy
  77 destroys an initialized condition variable at which point it is illegal
  78 to use it, though it may be initialized again.
  79 .Ss Condition Waiting
  80 The function
  81 .Fn cond_wait
  82 can be used to wait on a condition variable.
  83 A thread that waits on a condition variable blocks until another thread signals
  84 that the condition has changed, generally after making the condition that was
  85 false, true.
  86 .Pp
  87 The function
  88 .Fn cond_wait
  89 atomically release the mutex pointed to by
  90 .Fa mtx
  91 and blocks on the condition variable
  92 .Fa cond .
  93 When the thread returns, it will once again be holding
  94 .Fa mtx
  95 and must check the current state of the condition.
  96 There is no guarantee that another thread has not gotten in and changed the
  97 value before being woken.
  98 In addition, a thread blocking on a condition variable, may be woken spuriously,
  99 such as when a signal is received or
 100 .Fn fork
 101 is called .
 102 .Pp
 103 The function
 104 .Fn cond_timedwait
 105 allows a thread to block in a similar fashion to
 106 .Fn cond_wait ,
 107 except that when the absolute time specified in seconds since the epoch
 108 (based on
 109 .Sy CLOCK_REALTIME )
 110 in UTC, expires, then the thread will be woken up.
 111 The timeout is specified in
 112 .Fa abstime .
 113 .Ss Conditional Signaling
 114 The
 115 .Fn cnd_signal
 116 and
 117 .Fn cnd_broadcast
 118 functions can be used to signal threads waiting on the condition variable
 119 .Fa cnd
 120 that they should be woken up and check the variable again.
 121 The
 122 .Fn cnd_signal
 123 function will only wake a single thread that is blocked on the
 124 condition variable
 125 .Fa cnd ;
 126 while
 127 .Fn cnd_broadcast
 128 will wake up every thread waiting on the condition variable
 129 .Fa cnd .
 130 .Pp
 131 A thread calling either
 132 .Fn cnd_signal
 133 or
 134 .Fn cnd_broadcast
 135 is not required to hold any of the mutexes that are associated with the
 136 condition variable.
 137 .Pp
 138 If there are no threads currently blocked in the condition variable
 139 .Fa cnd
 140 then neither function has an effect.
 141 .Sh RETURN VALUES
 142 Upon successful completion, the
 143 .Fn cond_init
 144 function returns
 145 .Sy thrd_success.
 146 If insufficient memory was available, then
 147 .Sy thrd_nomem
 148 is returned; otherwise, if any other error occurred,
 149 .Sy thrd_error
 150 is returned.
 151 .Pp
 152 Upon successful completion, the
 153 .Fn cond_broadcast ,
 154 .Fn cond_signal ,
 155 and
 156 .Fn cond_wait
 157 functions return
 158 .Sy thrd_success .
 159 Otherwise, they return
 160 .Sy thrd_error
 161 to indicate that an error occurred and they were unable to complete.
 162 .Pp
 163 Upon successful completion, the
 164 .Fn cond_timedwait
 165 function returns
 166 .Sy thrd_success .
 167 If
 168 .Fa abstime
 169 expires without being signaled, it instead returns
 170 .Sy thrd_timedout .
 171 Otherwise,
 172 .Sy thrd_error
 173 is returned to indicate an error.
 174 .Sh INTERFACE STABILITY
 175 .Sy Standard
 176 .Sh MT-LEVEL
 177 .Sy MT-Safe
 178 .Sh SEE ALSO
 179 .Xr cond_braodcast 3C ,
 180 .Xr cond_destroy 3C ,
 181 .Xr cond_init 3C ,
 182 .Xr cond_signal 3C ,
 183 .Xr cond_timedwait 3C ,
 184 .Xr cond_wait 3C ,
 185 .Xr threads 3HEAD ,
 186 .Xr attributes 5 ,
 187 .Xr threads 5