88191d1c03bab4b9683dae89a0abdbdc39ac2ab2
[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 .\" $DragonFly: src/share/man/man9/callout.9,v 1.6 2008/05/02 02:05:06 swildner Exp $
39 .\"
40 .Dd November 14, 2007
41 .Dt CALLOUT 9
42 .Os
43 .Sh NAME
44 .Nm callout_init ,
45 .Nm callout_init_mp ,
46 .Nm callout_reset ,
47 .Nm callout_stop ,
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 int
67 .Fn callout_active "struct callout *c"
68 .Ft int
69 .Fn callout_pending "struct callout *c"
70 .Fn callout_deactivate "struct callout *c"
71 .Sh DESCRIPTION
72 The
73 .Nm callout
74 facility provides a mechanism to execute a function at a given time.
75 The timer is based on the hardclock timer which ticks
76 .Dv hz
77 times per second.
78 .Pp
79 Clients of the
80 .Nm callout
81 facility are responsible for providing pre-allocated callout structures, or
82 .Dq handles .
83 The
84 .Nm callout
85 facility replaces the historic
86 .Bx
87 functions
88 .Fn timeout
89 and
90 .Fn untimeout .
91 .Pp
92 The
93 .Fn callout_init
94 function initializes the callout handle
95 .Fa c
96 so it can be passed to
97 .Fn callout_stop
98 or
99 .Fn callout_reset
100 without any side effects.
101 The MP version of this function,
102 .Fn callout_init_mp ,
103 requires that the callback function installed by
104 .Fn callout_reset
105 be MP safe.
106 .Pp
107 The
108 .Fn callout_reset
109 function resets and starts the timer associated with the callout handle
110 .Fa c .
111 When the timer expires after
112 .Fa ticks Ns No /hz
113 seconds, the function specified by
114 .Fa func
115 will be called with the argument
116 .Fa arg .
117 .Pp
118 The function
119 .Fn callout_stop
120 cancels the callout associated with the callout handle
121 .Fa c
122 if it is currently pending.
123 It is safe to call
124 .Fn callout_stop
125 on a callout that is not pending, so long as it is initialized.
126 If the callout is not set, has already been serviced or is currently
127 being serviced, then zero will be returned.
128 .Pp
129 The
130 .Fn callout_pending
131 macro tests if the callout handle
132 .Fa c
133 is pending.
134 A pending callout is one that has been started and whose function has not
135 yet been called.
136 .Pp
137 The
138 .Fn callout_active
139 macro returns true if a timer has been started but not explicitly stopped,
140 even if it has already fired.
141 .Pp
142 The
143 .Fn callout_deactivate
144 macro deactivates the specified callout
145 .Fa c .
146 .Pp
147 The
148 .Fn callout_active ,
149 .Fn callout_pending
150 and
151 .Fn callout_deactivate
152 macros may only be used when the state of the callout structure is stable,
153 meaning from within the callback function or after the callback function
154 has been called but the timer has not yet been reset.
155 .Sh RETURN VALUES
156 The
157 .Fn callout_stop
158 function and the
159 .Fn callout_pending
160 macro return non-zero if the callout is still pending or zero otherwise.
161 The
162 .Fn callout_active
163 macro returns non-zero if the callout is active or zero otherwise.