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 November 30, 2014
  40 .Dt CALLOUT 9
  41 .Os
  42 .Sh NAME
  43 .Nm callout_init ,
  44 .Nm callout_init_lk ,
  45 .Nm callout_init_mp ,
  46 .Nm callout_reset ,
  47 .Nm callout_stop ,
  48 .Nm callout_stop_async ,
  49 .Nm callout_stop_sync ,
  50 .Nm callout_active ,
  51 .Nm callout_pending ,
  52 .Nm callout_deactivate
  53 .Nd execute a function after a specified length of time
  54 .Sh SYNOPSIS
  55 .In sys/types.h
  56 .In sys/systm.h
  57 .Bd -literal
  58 typedef void timeout_t (void *);
  59 .Ed
  60 .Ft void
  61 .Fn callout_init "struct callout *c"
  62 .Ft void
  63 .Fn callout_init_lk "struct callout *c" "struct lock *lk"
  64 .Ft void
  65 .Fn callout_init_mp "struct callout *c"
  66 .Ft void
  67 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
  68 .Ft int
  69 .Fn callout_stop "struct callout *c"
  70 .Ft void
  71 .Fn callout_stop_async "struct callout *c"
  72 .Ft int
  73 .Fn callout_stop_sync "struct callout *c"
  74 .Ft int
  75 .Fn callout_active "struct callout *c"
  76 .Ft int
  77 .Fn callout_pending "struct callout *c"
  78 .Fn callout_deactivate "struct callout *c"
  79 .Sh DESCRIPTION
  80 The
  81 .Nm callout
  82 facility provides a mechanism to execute a function at a given time.
  83 The timer is based on the hardclock timer which ticks
  84 .Dv hz
  85 times per second.
  86 .Pp
  87 Clients of the
  88 .Nm callout
  89 facility are responsible for providing pre-allocated callout structures, or
  90 .Dq handles .
  91 The
  92 .Nm callout
  93 facility replaces the historic
  94 .Bx
  95 functions
  96 .Fn timeout
  97 and
  98 .Fn untimeout .
  99 .Pp
 100 The
 101 .Fn callout_init
 102 function initializes the callout handle
 103 .Fa c
 104 so it can be passed to
 105 .Fn callout_stop
 106 or
 107 .Fn callout_reset
 108 without any side effects.
 109 The MP version of this function,
 110 .Fn callout_init_mp ,
 111 requires that the callback function installed by
 112 .Fn callout_reset
 113 be MP safe.
 114 .Pp
 115 The
 116 .Fn callout_init_lk
 117 function associates the callout handle
 118 .Fa c
 119 with a lock specified by
 120 .Fa lk .
 121 The
 122 .Nm callout
 123 subsystem acquires the associated lock before calling the callout function
 124 and releases it after the function returns.
 125 .Pp
 126 The
 127 .Fn callout_reset
 128 function resets and starts the timer associated with the callout handle
 129 .Fa c .
 130 When the timer expires after
 131 .Fa ticks Ns No /hz
 132 seconds, the function specified by
 133 .Fa func
 134 will be called with the argument
 135 .Fa arg .
 136 .Pp
 137 The function
 138 .Fn callout_stop
 139 cancels the callout associated with the callout handle
 140 .Fa c
 141 if it is currently pending.
 142 It is safe to call
 143 .Fn callout_stop
 144 on a callout that is not pending, so long as it is initialized.
 145 If the callout is not set, has already been serviced or is currently
 146 being serviced, then zero will be returned.
 147 The
 148 .Fn callout_stop_async
 149 function is identical to
 150 .Fn callout_stop
 151 without a return value.
 152 .Pp
 153 The
 154 .Fn callout_stop_sync
 155 function is a synchronous version of
 156 .Fn callout_stop
 157 which ensures that the callout function has completed operation (if it
 158 was running) before returning.
 159 .Pp
 160 The
 161 .Fn callout_pending
 162 macro tests if the callout handle
 163 .Fa c
 164 is pending.
 165 A pending callout is one that has been started and whose function has not
 166 yet been called.
 167 .Pp
 168 The
 169 .Fn callout_active
 170 macro returns true if a timer has been started but not explicitly stopped,
 171 even if it has already fired.
 172 .Pp
 173 The
 174 .Fn callout_deactivate
 175 macro deactivates the specified callout
 176 .Fa c .
 177 .Pp
 178 The
 179 .Fn callout_active ,
 180 .Fn callout_pending
 181 and
 182 .Fn callout_deactivate
 183 macros may only be used when the state of the callout structure is stable,
 184 meaning from within the callback function or after the callback function
 185 has been called but the timer has not yet been reset.
 186 .Sh RETURN VALUES
 187 The
 188 .Fn callout_stop
 189 function and the
 190 .Fn callout_pending
 191 macro return non-zero if the callout is still pending or zero otherwise.
 192 The
 193 .Fn callout_active
 194 macro returns non-zero if the callout is active or zero otherwise.