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