1.\" $NetBSD: cnd.3,v 1.2 2019/04/27 10:57:11 wiz Exp $ 2.\" 3.\" Copyright (c) 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kamil Rytarowski. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 16, 2016 31.Dt CND 3 32.Os 33.Sh NAME 34.Nm cnd 35.Nd condition variable functions 36.Sh LIBRARY 37.Lb libpthread 38.Sh SYNOPSIS 39.In threads.h 40.Ft int 41.Fn cnd_broadcast "cnd_t *cond" 42.Ft void 43.Fn cnd_destroy "cnd_t *cond" 44.Ft int 45.Fn cnd_init "cnd_t *cond" 46.Ft int 47.Fn cnd_signal "cnd_t *cond" 48.Ft int 49.Fo cnd_timedwait 50.Fa "cnd_t * __restrict cond" 51.Fa "mtx_t * __restrict mtx" 52.Fa "const struct timespec * __restrict ts" 53.Fc 54.Ft int 55.Fn cnd_wait "cnd_t *cond" "mtx_t *mtx" 56.Sh DESCRIPTION 57The 58.Fn cnd_broadcast 59function unblocks all threads that are blocked on a condition variable 60.Fa cond 61at the time of the call. 62If no thread is blocked on the 63.Fa cond 64condition variable at the time of the call, 65the function does nothing and returns success. 66.Pp 67The 68.Fn cnd_destroy 69function destroys the 70.Fa cond 71condition variable. 72.Pp 73The 74.Fn cnd_init 75function initializes a new 76.Fa cond 77variable. 78.Pp 79The 80.Fn cnd_signal 81function unblock one thread that currently waits on the 82.Fa cond 83variable. 84If there are no threads blocked, 85.Fn cnd_signal 86does nothing and returns success. 87.Pp 88The 89.Fn cnd_timedwait 90function atomically unlocks the mutex 91.Fa mtx 92and blocks on the condition variable 93.Fa cond 94until a thread is signalled by a call to 95.Fn cnd_signal 96or 97.Fn cnd_broadcast 98or timeout 99.Fa ts 100has been reached. 101The 102.Fa ts 103parameter is specified as 104.Dv TIME_UTC 105based calendar time. 106If the mutex is not locked by the calling thread then behavior is undefined. 107.Pp 108The 109.Fn cnd_wait 110function atomically unlocks the mutex 111.Fa mtx 112and tries to block on the conditional variable 113.Fa cond 114until a thread is signalled by a call to 115.Fn cnd_signal 116or 117.Fn cnd_broadcast . 118The 119.Fa mtx 120mutex is locked again before the function returns. 121If the mutex is not locked by the calling thread then behavior is undefined. 122.Sh RETURN VALUES 123The 124.Fn cnd_broadcast 125function returns 126.Dv thrd_success 127on success or 128.Dv thrd_error 129on failure. 130.Pp 131The 132.Fn cnd_destroy 133function returns no value. 134.Pp 135The 136.Fn cnd_init 137function returns 138.Dv thrd_success 139on success or 140.Dv thrd_error 141on failure. 142.Pp 143The 144.Fn cnd_signal 145function returns 146.Dv thrd_success 147on success or 148.Dv thrd_error 149on failure. 150.Pp 151The 152.Fn cnd_timedwait 153function returns 154.Dv thrd_success 155on success, otherwise 156.Dv thrd_timedout 157to indicate that system time has reached or exceeded the time specified in 158.Dv ts , 159or 160.Dv thrd_error 161on failure. 162.Pp 163The 164.Fn cnd_wait 165function returns 166.Dv thrd_success 167on success or 168.Dv thrd_error 169on failure. 170.Sh SEE ALSO 171.Xr pthread_cond 3 , 172.Xr threads 3 173.Sh STANDARDS 174The 175.Nm 176interface conforms to 177.St -isoC-2011 . 178.Sh HISTORY 179This interface first appeared in 180.Nx 9 . 181.Sh AUTHORS 182.An Kamil Rytarowski Aq Mt kamil@NetBSD.org 183