xref: /illumos-gate/usr/src/man/man3c/cnd.3c (revision 8c69cc8fbe729fa7b091e901c4b50508ccc6bb33)
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
56The
57.Sy cnd
58family of functions implement condition variables which allow threads
59within a process to wait until a condition occurs and be signaled when
60it does.
61These functions behave similar to both the POSIX threads and illumos threads;
62however, they have slightly different call signatures and return values.
63For more information, see
64.Xr threads 5 .
65Importantly, they do not allow for inter-process synchronization.
66.Ss Creating and Destroy Condition Variables
67The function
68.Fn cnd_init
69initializes the condition variable referred to by
70.Fa cnd .
71The condition variable is suitable for intra-process use.
72Initializing an already initialized condition variable results in undefined
73behavior.
74.Pp
75The function
76.Fn cnd_destroy
77destroys an initialized condition variable at which point it is illegal
78to use it, though it may be initialized again.
79.Ss Condition Waiting
80The function
81.Fn cond_wait
82can be used to wait on a condition variable.
83A thread that waits on a condition variable blocks until another thread signals
84that the condition has changed, generally after making the condition that was
85false, true.
86.Pp
87The function
88.Fn cond_wait
89atomically release the mutex pointed to by
90.Fa mtx
91and blocks on the condition variable
92.Fa cond .
93When the thread returns, it will once again be holding
94.Fa mtx
95and must check the current state of the condition.
96There is no guarantee that another thread has not gotten in and changed the
97value before being woken.
98In addition, a thread blocking on a condition variable, may be woken spuriously,
99such as when a signal is received or
100.Fn fork
101is called .
102.Pp
103The function
104.Fn cond_timedwait
105allows a thread to block in a similar fashion to
106.Fn cond_wait ,
107except that when the absolute time specified in seconds since the epoch
108(based on
109.Sy CLOCK_REALTIME )
110in UTC, expires, then the thread will be woken up.
111The timeout is specified in
112.Fa abstime .
113.Ss Conditional Signaling
114The
115.Fn cnd_signal
116and
117.Fn cnd_broadcast
118functions can be used to signal threads waiting on the condition variable
119.Fa cnd
120that they should be woken up and check the variable again.
121The
122.Fn cnd_signal
123function will only wake a single thread that is blocked on the
124condition variable
125.Fa cnd ;
126while
127.Fn cnd_broadcast
128will wake up every thread waiting on the condition variable
129.Fa cnd .
130.Pp
131A thread calling either
132.Fn cnd_signal
133or
134.Fn cnd_broadcast
135is not required to hold any of the mutexes that are associated with the
136condition variable.
137.Pp
138If there are no threads currently blocked in the condition variable
139.Fa cnd
140then neither function has an effect.
141.Sh RETURN VALUES
142Upon successful completion, the
143.Fn cond_init
144function returns
145.Sy thrd_success.
146If insufficient memory was available, then
147.Sy thrd_nomem
148is returned; otherwise, if any other error occurred,
149.Sy thrd_error
150is returned.
151.Pp
152Upon successful completion, the
153.Fn cond_broadcast ,
154.Fn cond_signal ,
155and
156.Fn cond_wait
157functions return
158.Sy thrd_success .
159Otherwise, they return
160.Sy thrd_error
161to indicate that an error occurred and they were unable to complete.
162.Pp
163Upon successful completion, the
164.Fn cond_timedwait
165function returns
166.Sy thrd_success .
167If
168.Fa abstime
169expires without being signaled, it instead returns
170.Sy thrd_timedout .
171Otherwise,
172.Sy thrd_error
173is 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_broadcast 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.h 3HEAD ,
186.Xr attributes 5 ,
187.Xr threads 5
188