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