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