callout.9: Mention callout_stop_sync().
[dragonfly.git] / share / man / man9 / callout.9
1 .\"     $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $
2 .\"
3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Paul Kranenburg.
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 .\" 3. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"        This product includes software developed by the NetBSD
20 .\"        Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\"    contributors may be used to endorse or promote products derived
23 .\"    from this software without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
29 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\"
37 .\" $FreeBSD: src/share/man/man9/timeout.9,v 1.9.2.6 2001/12/17 11:30:19 ru Exp $
38 .\"
39 .Dd February 8, 2014
40 .Dt CALLOUT 9
41 .Os
42 .Sh NAME
43 .Nm callout_init ,
44 .Nm callout_init_mp ,
45 .Nm callout_reset ,
46 .Nm callout_stop ,
47 .Nm callout_stop_sync ,
48 .Nm callout_active ,
49 .Nm callout_pending ,
50 .Nm callout_deactivate
51 .Nd execute a function after a specified length of time
52 .Sh SYNOPSIS
53 .In sys/types.h
54 .In sys/systm.h
55 .Bd -literal
56 typedef void timeout_t (void *);
57 .Ed
58 .Ft void
59 .Fn callout_init "struct callout *c"
60 .Ft void
61 .Fn callout_init_mp "struct callout *c"
62 .Ft void
63 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
64 .Ft int
65 .Fn callout_stop "struct callout *c"
66 .Ft void
67 .Fn callout_stop_sync "struct callout *c"
68 .Ft int
69 .Fn callout_active "struct callout *c"
70 .Ft int
71 .Fn callout_pending "struct callout *c"
72 .Fn callout_deactivate "struct callout *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 .Pp
81 Clients of the
82 .Nm callout
83 facility are responsible for providing pre-allocated callout structures, or
84 .Dq handles .
85 The
86 .Nm callout
87 facility replaces the historic
88 .Bx
89 functions
90 .Fn timeout
91 and
92 .Fn untimeout .
93 .Pp
94 The
95 .Fn callout_init
96 function initializes the callout handle
97 .Fa c
98 so it can be passed to
99 .Fn callout_stop
100 or
101 .Fn callout_reset
102 without any side effects.
103 The MP version of this function,
104 .Fn callout_init_mp ,
105 requires that the callback function installed by
106 .Fn callout_reset
107 be MP safe.
108 .Pp
109 The
110 .Fn callout_reset
111 function resets and starts the timer associated with the callout handle
112 .Fa c .
113 When the timer expires after
114 .Fa ticks Ns No /hz
115 seconds, the function specified by
116 .Fa func
117 will be called with the argument
118 .Fa arg .
119 .Pp
120 The function
121 .Fn callout_stop
122 cancels the callout associated with the callout handle
123 .Fa c
124 if it is currently pending.
125 It is safe to call
126 .Fn callout_stop
127 on a callout that is not pending, so long as it is initialized.
128 If the callout is not set, has already been serviced or is currently
129 being serviced, then zero will be returned.
130 The
131 .Fn callout_stop_sync
132 function is a synchronous version of
133 .Fn callout_stop
134 which ensures that the callout function has completed operation (if it
135 was running) before returning.
136 .Pp
137 The
138 .Fn callout_pending
139 macro tests if the callout handle
140 .Fa c
141 is pending.
142 A pending callout is one that has been started and whose function has not
143 yet been called.
144 .Pp
145 The
146 .Fn callout_active
147 macro returns true if a timer has been started but not explicitly stopped,
148 even if it has already fired.
149 .Pp
150 The
151 .Fn callout_deactivate
152 macro deactivates the specified callout
153 .Fa c .
154 .Pp
155 The
156 .Fn callout_active ,
157 .Fn callout_pending
158 and
159 .Fn callout_deactivate
160 macros may only be used when the state of the callout structure is stable,
161 meaning from within the callback function or after the callback function
162 has been called but the timer has not yet been reset.
163 .Sh RETURN VALUES
164 The
165 .Fn callout_stop
166 function and the
167 .Fn callout_pending
168 macro return non-zero if the callout is still pending or zero otherwise.
169 The
170 .Fn callout_active
171 macro returns non-zero if the callout is active or zero otherwise.