| blob | d3c12c16f69d3aface34742f68a5bc0e554e6f7e |
1 .\" $NetBSD: callout.9,v 1.24 2009/05/04 13:37:57 wiz Exp $
2 .\"
3 .\" Copyright (c) 2000, 2003, 2009 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Jason R. Thorpe.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd August 3, 2009
31 .Dt CALLOUT 9
32 .Os
33 .Sh NAME
34 .Nm callout_init ,
35 .Nm callout_destroy ,
36 .Nm callout_halt ,
37 .Nm callout_reset ,
38 .Nm callout_schedule ,
39 .Nm callout_setfunc ,
40 .Nm callout_stop ,
41 .Nm callout_pending ,
42 .Nm callout_expired ,
43 .Nm callout_invoking ,
44 .Nm callout_ack
45 .Nd execute a function after a specified length of time
46 .Sh SYNOPSIS
47 .In sys/callout.h
48 .Ft void
49 .Fn "callout_init" "callout_t *c" "u_int flags"
50 .Ft void
51 .Fn "callout_destroy" "callout_t *c"
52 .Ft void
53 .Fn "callout_reset" "callout_t *c" "int ticks" \
54 "void (*func)(void *)" "void *arg"
55 .Ft void
56 .Fn "callout_schedule" "callout_t *c" "int ticks"
57 .Ft void
58 .Fn "callout_setfunc" "callout_t *c" "void (*func)(void *)" "void *arg"
59 .Ft bool
60 .Fn "callout_stop" "callout_t *c"
61 .Ft bool
62 .Fn "callout_halt" "callout_t *c" "kmutex_t *interlock"
63 .Ft bool
64 .Fn "callout_pending" "callout_t *c"
65 .Ft bool
66 .Fn "callout_expired" "callout_t *c"
67 .Ft bool
68 .Fn "callout_active" "callout_t *c"
69 .Ft bool
70 .Fn "callout_invoking" "callout_t *c"
71 .Ft bool
72 .Fn "callout_ack" "callout_t *c"
73 .Sh DESCRIPTION
74 The
75 .Nm callout
76 facility provides a mechanism to execute a function at a given time.
77 The timer is based on the hardclock timer which ticks
78 .Dv hz
79 times per second.
80 The function is called at softclock interrupt level.
81 .Pp
82 Clients of the
83 .Nm callout
84 facility are responsible for providing pre-allocated
85 callout structures, or
86 .Dq handles .
87 The
88 .Nm callout
89 facility replaces the historic
90 .Ux
91 functions
92 .Fn timeout
93 and
94 .Fn untimeout .
95 .Sh FUNCTIONS
96 The
97 .Fn callout_init
98 function initializes the callout handle
99 .Fa c
100 for use.
101 No operations can be performed on the callout before it is initialized.
102 If the
103 .Fa flags
104 argument is
105 .Dv CALLOUT_MPSAFE ,
106 the handler will be called without getting the global kernel lock.
107 In this case it should only use functions that are multiprocessor
108 safe.
109 .Pp
110 .Fn callout_destroy
111 destroys the callout, preventing further use.
112 It is provided as a diagnostic facility intended to catch bugs.
113 To ensure future compatibility,
114 .Fn callout_destroy
115 should always be called when the callout is no longer required (for instance,
116 when a device is being detached).
117 .Pp
118 The
119 .Fn callout_reset
120 function resets and starts the timer associated with the callout handle
121 .Fa c .
122 When the timer expires after
123 .Fa ticks Ns No /hz
124 seconds, the function specified by
125 .Fa func
126 will be called with the argument
127 .Fa arg .
128 If the timer associated with the callout handle is already running,
129 the callout will simply be rescheduled to execute at the newly specified
130 time.
131 Once the timer is started, the callout handle is marked as
132 .Em PENDING .
133 Once the timer expires,
134 the handle is marked as
135 .Em EXPIRED
136 and
137 .Em INVOKING ,
138 and the
139 .Em PENDING
140 status is cleared.
141 .Pp
142 The
143 .Fn callout_setfunc
144 function sets the function and argument of the callout handle
145 .Fa c
146 to
147 .Fa func
148 and
149 .Fa arg
150 respectively.
151 The callout handle must already be initialized.
152 If a callout will always be used with the same function and argument,
153 then
154 .Fn callout_setfunc
155 used in conjunction with
156 .Fn callout_schedule
157 is slightly more efficient than using
158 .Fn callout_reset .
159 .Pp
160 The
161 .Fn callout_stop
162 function requests that the timer associated with the callout handle
163 .Fa c
164 be stopped.
165 The
166 .Em PENDING
167 and
168 .Em EXPIRED
169 status for the callout handle is cleared.
170 It is safe to call
171 .Fn callout_stop
172 on a callout handle that is not pending, so long as it is initialized.
173 .Fn callout_stop
174 will return a non-zero value if the callout was
175 .Em EXPIRED .
176 Note that
177 .Fn callout_stop
178 can return while the callout is running on a different CPU or at a
179 different interrupt priority level on the current CPU.
180 It can only be said to prevent the callout from firing in the future,
181 unless explicitly re-scheduled.
182 To stop a callout and wait for completion, use
183 .Fn callout_halt .
184 .Pp
185 .Fn callout_halt
186 acts much like
187 .Fn callout_stop ,
188 but waits for the callout to complete if it is currently in-flight.
189 .Fn callout_halt
190 may not be called from a hard interrupt handler as it will sleep if the
191 callout is currently executing.
192 If the callout can take locks (such as mutexes or RW locks), the caller of
193 .Fn callout_halt
194 must not hold any of those locks, otherwise the two could deadlock.
195 To facilitate this,
196 .Fn callout_halt
197 can optionally release a single mutex specified by the
198 .Fa interlock
199 parameter.
200 If
201 .Fa interlock
202 is not
203 .Dv NULL
204 and the calling thread must wait for the callout to complete,
205 .Fa interlock
206 will be released before waiting and re-acquired before returning.
207 If no wait is required,
208 .Fa interlock
209 will not be released.
210 However, to avoid race conditions the caller should always assume that
211 .Fa interlock
212 has been released and reacquired, and act accordingly.
213 .Pp
214 The
215 .Fn callout_pending
216 function tests the
217 .Em PENDING
218 status of the callout handle
219 .Fa c .
220 A
221 .Em PENDING
222 callout is one that has been started and whose function has not yet
223 been called.
224 Note that it is possible for a callout's timer to have expired without
225 its function being called if interrupt level has not dropped low enough
226 to let softclock interrupts through.
227 Note that it is only safe to test
228 .Em PENDING
229 status when at softclock interrupt level or higher.
230 .Pp
231 The
232 .Fn callout_expired
233 function tests to see if the callout's timer has expired and its
234 function called.
235 .Pp
236 The
237 .Fn callout_active
238 function returns true if a timer has been started but not explicitly stopped,
239 even if it has already fired.
240 .Fn callout_active foo
241 is logically the same as
242 .Fn callout_pending foo
243 ||
244 .Fn callout_expired foo ;
245 it is implemented as a separate function for compatibility with
246 .Fx
247 and for the special case of
248 .Fn TCP_TIMER_ISARMED .
249 Its use is not recommended.
250 .Pp
251 The
252 .Fn callout_invoking
253 function tests the
254 .Em INVOKING
255 status of the callout handle
256 .Fa c .
257 This flag is set just before a callout's function is being called.
258 Since the priority level is lowered prior to invocation of the
259 callout function, other pending higher-priority code may run before
260 the callout function is allowed to run.
261 This may create a race condition if this higher-priority code
262 deallocates storage containing one or more callout structures whose
263 callout functions are about to be run.
264 In such cases, one technique to prevent references to deallocated
265 storage would be to test whether any callout functions are in the
266 .Em INVOKING
267 state using
268 .Fn callout_invoking ,
269 and if so, to mark the data structure and defer storage
270 deallocation until the callout function is allowed to run.
271 For this handshake protocol to work, the callout function will
272 have to use the
273 .Fn callout_ack
274 function to clear this flag.
275 .Pp
276 The
277 .Fn callout_ack
278 function clears the
279 .Em INVOKING
280 state in the callout handle
281 .Fa c .
282 This is used in situations where it is necessary to protect against
283 the race condition described under
284 .Fn callout_invoking .
285 .Sh CONCURRENCY
286 The callout facility performs locking internally in order to guarantee the
287 atomicity of individual operations performed on callouts.
288 It does not provide life cycle management of user-provided callout data
289 structures, nor does it ensure that groups of operations (multiple function
290 calls) are performed atomically.
291 These aspects of callout management are the responsibility of the user of
292 the callout facility.
293 .Pp
294 Scheduled callouts may be active concurrently in a context different to the
295 user of the callout facility: on another CPU, or at a different interrupt
296 priority level or thread on the current CPU.
297 The callout facility provides only one guarantee in this regard: any given
298 callout will never have multiple concurrent invocations.
299 .Sh SEE ALSO
300 .Xr condvar 9 ,
301 .Xr hz 9 ,
302 .Xr softint 9 ,
303 .Xr workqueue 9
304 .Sh HISTORY
305 The
306 .Nm callout
307 facility was implemented by Artur Grabowski and Thomas Nordin, based
308 on the work of G. Varghese and A. Lauck, described in the paper
309 Hashed and Hierarchical Timing Wheels: Data Structures for the
310 Efficient Implementation of a Timer Facility
311 in the Proceedings of the 11th ACM Annual Symposium on Operating System
312 Principles, Austin, Texas, November 1987.
313 It was adapted to the
314 .Nx
315 kernel by Jason R. Thorpe.