1.\" $OpenBSD: __thrsleep.2,v 1.4 2013/07/16 15:21:11 schwarze 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: July 16 2013 $ 18.Dt __THRSLEEP 3 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 neither 155.Dv CLOCK_REALTIME 156nor 157.Dv CLOCK_MONOTONIC . 158.El 159.Pp 160.Fn __thrwakeup 161may return the following error: 162.Bl -tag -width Er 163.It Bq Er ESRCH 164No threads calling 165.Fn __thrsleep 166with the same 167.Fa id 168were found. 169.El 170.Sh SEE ALSO 171.Xr pthread_cond_wait 3 , 172.Xr pthread_mutex_lock 3 , 173.Xr tsleep 9 174.Sh STANDARDS 175The 176.Fn __thrsleep 177and 178.Fn __thrwakeup 179functions are specific to 180.Ox 181and should not be used in portable applications. 182.Sh HISTORY 183The 184.Fn thrsleep 185and 186.Fn thrwakeup 187syscalls appeared in 188.Ox 3.9 . 189The 190.Fa clock_id 191and 192.Fa abstime 193arguments were added in 194.Ox 4.9 . 195The functions were renamed to 196.Fn __thrsleep 197and 198.Fn __thrwakeup 199and the 200.Fa abort 201argument was added in 202.Ox 5.1 203.Sh AUTHORS 204.An -nosplit 205The 206.Fn thrsleep 207and 208.Fn thrwakeup 209syscalls were created by 210.An Ted Unangst Aq Mt tedu@OpenBSD.org . 211This manual page was written by 212.An Philip Guenther Aq Mt guenther@OpenBSD.org . 213