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