1.\" $OpenBSD: __thrsleep.2,v 1.7 2018/04/24 16:28:42 pirofti 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: April 24 2018 $ 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 ECANCELED 152A signal arrived and 153.Fa SA_RESTART 154was set. 155.It Bq Er EINVAL 156The 157.Fa clock_id 158argument is not a valid 159.Xr clock_gettime 2 160clock id 161or 162.Fa abstime 163specified a nanosecond value less than zero or greater than 1000 million. 164.El 165.Pp 166.Fn __thrwakeup 167may return the following error: 168.Bl -tag -width Er 169.It Bq Er ESRCH 170No threads calling 171.Fn __thrsleep 172with the same 173.Fa id 174were found. 175.El 176.Sh SEE ALSO 177.Xr sigaction 2 , 178.Xr pthread_cond_wait 3 , 179.Xr pthread_mutex_lock 3 , 180.Xr tsleep 9 181.Sh STANDARDS 182The 183.Fn __thrsleep 184and 185.Fn __thrwakeup 186functions are specific to 187.Ox 188and should not be used in portable applications. 189.Sh HISTORY 190The 191.Fn thrsleep 192and 193.Fn thrwakeup 194syscalls appeared in 195.Ox 3.9 . 196The 197.Fa clock_id 198and 199.Fa abstime 200arguments were added in 201.Ox 4.9 . 202The functions were renamed to 203.Fn __thrsleep 204and 205.Fn __thrwakeup 206and the 207.Fa abort 208argument was added in 209.Ox 5.1 210.Sh AUTHORS 211.An -nosplit 212The 213.Fn thrsleep 214and 215.Fn thrwakeup 216syscalls were created by 217.An Ted Unangst Aq Mt tedu@OpenBSD.org . 218This manual page was written by 219.An Philip Guenther Aq Mt guenther@OpenBSD.org . 220