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