summaryrefslogtreecommitdiffstats
path: root/share/man/man9/timeout.9
blob: beb2553de2ce7be9c7301dc6331b46c8c04b24e1 (plain)
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
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
.\"	$NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd September 10, 1996
.Dt TIMEOUT 9
.Os
.Sh NAME
.Nm timeout ,
.Nm untimeout ,
.Nm callout_handle_init ,
.Nm callout_init ,
.Nm callout_stop ,
.Nm callout_drain ,
.Nm callout_reset
.Nd execute a function after a specified length of time
.Sh SYNOPSIS
.In sys/types.h
.In sys/systm.h
.Pp
.Bd -literal
typedef void timeout_t (void *);
.Ed
.Ft struct callout_handle
.Fn timeout "timeout_t *func" "void *arg" "int ticks"
.Ft void
.Fn callout_handle_init "struct callout_handle *handle"
.Pp
.Bd -literal
struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
.Ed
.Ft void
.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
.Ft void
.Fn callout_init "struct callout *c" "int mpsafe"
.Ft int
.Fn callout_stop "struct callout *c"
.Ft int
.Fn callout_drain "struct callout *c"
.Ft void
.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
.Sh DESCRIPTION
The function
.Fn timeout
schedules a call to the function given by the argument
.Fa func
to take place after
.Fa ticks Ns No /hz
seconds.
Non-positive values of
.Fa ticks
are silently converted to the value
.Sq 1 .
.Fa func
should be a pointer to a function that takes a
.Fa void *
argument.
Upon invocation,
.Fa func
will receive
.Fa arg
as its only argument.
The return value from
.Fn timeout
is a
.Ft struct callout_handle
which can be used in conjunction with the
.Fn untimeout
function to request that a scheduled timeout be canceled.
The
.Fn timeout
call is the old style and new code should use the callout_* functions.
.Pp
The function
.Fn callout_handle_init
can be used to initialize a handle to a state which will cause
any calls to untimeout with that handle to return with no side
effects.
.Pp
Assigning a callout handle the value of
.Fn CALLOUT_HANDLE_INITIALIZER
performs the same function as
.Fn callout_handle_init
and is provided for use on statically declared or global callout handles.
.Pp
The function
.Fn untimeout
cancels the timeout associated with
.Fa handle
using the
.Fa func
and
.Fa arg
arguments to validate the handle.
If the handle does not correspond to a timeout with
the function
.Fa func
taking the argument
.Fa arg
no action is taken.
.Fa handle
must be initialized by a previous call to
.Fn timeout ,
.Fn callout_handle_init ,
or assigned the value of
.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
before being passed to
.Fn untimeout .
The behavior of calling untimeout without a previously initialized handle
is undefined.
The
.Fn untimeout
call is the old style and new code should use the callout_* functions.
.Pp
As handles are recycled by the system, it is possible (although unlikely)
that a handle from one invocation of
.Fn timeout
may match the handle of another invocation of
.Fn timeout
if both calls used the same function pointer and argument, and the first
timeout is expired or canceled before the second call.
The timeout facility offers O(1) running time for
.Fn timeout
and
.Fn untimeout .
Timeouts are executed from
.Fn softclock
at
.Fn splsoftclock .
Thus they are protected from re-entrancy.
.Pp
The functions
.Fn callout_init ,
.Fn callout_stop ,
.Fn callout_drain
and
.Fn callout_reset
are low-level routines for clients who wish to allocate their own
callout structures.
.Pp
The function
.Fn callout_init
initializes a callout so it can be passed to
.Fn callout_stop ,
.Fn callout_drain 
or
.Fn callout_reset
without any side effects.
If the
.Fa mpsafe
argument is zero,
the callout structure is not considered to be
.Dq multi-processor safe ;
that is,
the Giant lock will be acquired before calling the callout function,
and released when the callout function returns.
.Pp
The function
.Fn callout_stop
cancels a callout if it is currently pending.
If the callout is pending, then
.Fn callout_stop
will return a non-zero value.
If the callout has already been serviced or is currently being serviced,
then zero will be returned.
.Pp
The function
.Fn callout_drain
is identical to
.Fn callout_stop
except that it will wait for the callout to be completed if it is
already in progress.
This function MUST NOT be called while holding any
locks on which the callout might block, or deadlock will result.
.Pp
The function
.Fn callout_reset
first calls
.Fn callout_stop
to disestablish the callout, and then establishes a new callout in the
same manner as
.Fn timeout .
.Sh RETURN VALUES
The
.Fn timeout
function returns a
.Ft struct callout_handle
that can be passed to
.Fn untimeout .
The
.Fn callout_stop
and
.Fn callout_drain
functions return non-zero if the callout was still pending when it was
called or zero otherwise.
.Sh HISTORY
The current timeout and untimeout routines are based on the work of
.An Adam M. Costello
and
.An George Varghese ,
published in a technical report entitled
.%T "Redesigning the BSD Callout and Timer Facilities"
and modified slightly for inclusion in
.Fx
by
.An Justin T. Gibbs .
The original work on the data structures used in this implementation
was published by
.An G. Varghese
and
.An A. Lauck
in the paper
.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
in the
.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
The current implementation replaces the long standing
.Bx
linked list
callout mechanism which offered O(n) insertion and removal running time
but did not generate or require handles for untimeout operations.
OpenPOWER on IntegriCloud