1.\" $OpenBSD: __thrsleep.2,v 1.6 2016/09/03 17:02:22 akfaew Exp $ 2.\" 3.\" Copyright (c) 2012 Philip Guenther <guenther@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 3 2016 $ 18.Dt __THRSLEEP 2 19.Os 20.Sh NAME 21.Nm __thrsleep , 22.Nm __thrwakeup 23.Nd userspace thread sleep and wakeup 24.Sh SYNOPSIS 25.In sys/time.h 26.Ft int 27.Fn __thrsleep "const volatile void *id" "clockid_t clock_id" "const struct timespec *abstime" "void *lock" "const int *abort" 28.Ft int 29.Fn __thrwakeup "const volatile void *id" "int count" 30.Sh DESCRIPTION 31The 32.Fn __thrsleep 33and 34.Fn __thrwakeup 35functions provide thread sleep and wakeup primitives with which 36synchronization primitives such as mutexes and condition variables 37can be implemented. 38.Fn __thrsleep 39blocks the calling thread on the abstract 40.Dq wait channel 41identified by the 42.Fa id 43argument until another thread calls 44.Fn __thrwakeup 45with the same 46.Fa id 47value. 48If the 49.Fa abstime 50argument is not 51.Dv NULL , 52then it specifies an absolute time, 53measured against the 54.Fa clock_id 55clock, 56after which 57.Fn __thrsleep 58should time out and return. 59If the specified time is in the past then 60.Fn __thrsleep 61will return immediately without blocking. 62.Pp 63The 64.Fa lock 65argument, 66if not 67.Dv NULL , 68points to a locked spinlock that will be unlocked by 69.Fn __thrsleep 70atomically with respect to calls to 71.Fn __thrwakeup , 72such that if another thread locks the spinlock before calling 73.Fn __thrwakeup 74with the same 75.Fa id , 76then the thread that called 77.Fn __thrsleep 78will be eligible for being woken up and unblocked. 79.Pp 80The 81.Fa abort 82argument, 83if not 84.Dv NULL , 85points to an 86.Vt int 87that will be examined after unlocking the spinlock pointed to by 88.Fa lock 89and immediately before blocking. 90If that 91.Vt int 92is non-zero then 93.Fn __thrsleep 94will immediately return 95.Er EINTR 96without blocking. 97This provides a mechanism for a signal handler to keep a call to 98.Fn __thrsleep 99from blocking, 100even if the signal is delivered immediately before the call. 101.Pp 102The 103.Fn __thrwakeup 104function unblocks one or more threads that are sleeping on the 105wait channel identified by 106.Fa id . 107The number of threads unblocked is specified by the 108.Fa count 109argument, 110except that if zero is specified then all threads sleeping on that 111.Fa id 112are unblocked. 113.Sh RETURN VALUES 114.Fn __thrsleep 115will return zero if woken by a matching call to 116.Fn __thrwakeup , 117otherwise an error number will be returned to indicate the error. 118.Pp 119.Fn __thrwakeup 120will return zero if at least one matching call to 121.Fn __thrsleep 122was unblocked, 123otherwise an error number will be returned to indicate the error. 124.Sh ERRORS 125.Fn __thrsleep 126and 127.Fn __thrwakeup 128will fail if: 129.Bl -tag -width Er 130.It Bq Er EINVAL 131The 132.Fa ident 133argument is 134.Dv NULL . 135.El 136.Pp 137In addition, 138.Fn __thrsleep 139may return one of the following errors: 140.Bl -tag -width Er 141.It Bq Er EWOULDBLOCK 142The time specified by the 143.Fa abstime 144and 145.Fa clock_id 146arguments was reached. 147.It Bq Er EINTR 148A signal arrived or the 149.Fa abort 150argument pointed to a non-zero value. 151.It Bq Er EINVAL 152The 153.Fa clock_id 154argument is not a valid 155.Xr clock_gettime 2 156clock id. 157.El 158.Pp 159.Fn __thrwakeup 160may return the following error: 161.Bl -tag -width Er 162.It Bq Er ESRCH 163No threads calling 164.Fn __thrsleep 165with the same 166.Fa id 167were found. 168.El 169.Sh SEE ALSO 170.Xr pthread_cond_wait 3 , 171.Xr pthread_mutex_lock 3 , 172.Xr tsleep 9 173.Sh STANDARDS 174The 175.Fn __thrsleep 176and 177.Fn __thrwakeup 178functions are specific to 179.Ox 180and should not be used in portable applications. 181.Sh HISTORY 182The 183.Fn thrsleep 184and 185.Fn thrwakeup 186syscalls appeared in 187.Ox 3.9 . 188The 189.Fa clock_id 190and 191.Fa abstime 192arguments were added in 193.Ox 4.9 . 194The functions were renamed to 195.Fn __thrsleep 196and 197.Fn __thrwakeup 198and the 199.Fa abort 200argument was added in 201.Ox 5.1 202.Sh AUTHORS 203.An -nosplit 204The 205.Fn thrsleep 206and 207.Fn thrwakeup 208syscalls were created by 209.An Ted Unangst Aq Mt tedu@OpenBSD.org . 210This manual page was written by 211.An Philip Guenther Aq Mt guenther@OpenBSD.org . 212