1.\" $OpenBSD: __thrsleep.2,v 1.1 2012/03/13 15:55:46 guenther 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: March 13 2012 $ 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.It Bq Er ENOTSUP 136The kern.rthreads sysctl was not enabled. 137.El 138.Pp 139In addition, 140.Fn __thrsleep 141may return one of the following errors: 142.Bl -tag -width Er 143.It Bq Er EWOULDBLOCK 144The time specified by the 145.Fa abstime 146and 147.Fa clock_id 148arguments was reached. 149.It Bq Er EINTR 150A signal arrived or the 151.Fa abort 152argument pointed to a non-zero value. 153.It Bq Er EINVAL 154The 155.Fa clock_id 156argument is neither 157.Dv CLOCK_REALTIME 158nor 159.Dv CLOCK_MONOTONIC . 160.El 161.Pp 162.Fn __thrwakeup 163may return the following error: 164.Bl -tag -width Er 165.It Bq Er ESRCH 166No threads calling 167.Fn __thrsleep 168with the same 169.Fa id 170were found. 171.El 172.Sh SEE ALSO 173.Xr pthread_cond_wait 3 , 174.Xr pthread_mutex_lock 3 , 175.Xr tsleep 9 176.Sh STANDARDS 177The 178.Fn __thrsleep 179and 180.Fn __thrwakeup 181functions are specific to 182.Ox 183and should not be used in portable applications. 184.Sh HISTORY 185The 186.Fn thrsleep 187and 188.Fn thrwakeup 189syscalls appeared in 190.Ox 4.1 . 191The 192.Fa clock_id 193and 194.Fa abstime 195arguments were added in 196.Ox 4.9 . 197The functions were renamed to 198.Fn __thrsleep 199and 200.Fn __thrwakeup 201and the 202.Fa abort 203argument was added in 204.Ox 5.1 205.Sh AUTHORS 206.An -nosplit 207The 208.Fn thrsleep 209and 210.Fn thrwakeup 211syscalls were created by 212.An Ted Unangst Aq tedu@OpenBSD.org . 213This manual page was written by 214.An Philip Guenther Aq guenther@OpenBSD.org . 215