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