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.4 2007/03/11 20:04:18 swildner Exp $
  39 .\"
  40 .Dd March 11, 2007
  41 .Dt TIMEOUT 9
  42 .Os
  43 .Sh NAME
  44 .Nm timeout ,
  45 .Nm untimeout ,
  46 .Nm callout_handle_init ,
  47 .Nm callout_init ,
  48 .Nm callout_stop ,
  49 .Nm callout_reset
  50 .Nd execute a function after a specified length of time
  51 .Sh SYNOPSIS
  52 .In sys/types.h
  53 .In sys/systm.h
  54 .Pp
  55 .Bd -literal
  56 typedef void timeout_t (void *);
  57 .Ed
  58 .Ft struct callout_handle
  59 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
  60 .Ft void
  61 .Fn callout_handle_init "struct callout_handle *handle"
  62 .Pp
  63 .Bd -literal
  64 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
  65 .Ed
  66 .Ft void
  67 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
  68 .Ft void
  69 .Fn callout_init "struct callout *c"
  70 .Ft int
  71 .Fn callout_stop "struct callout *c"
  72 .Ft void
  73 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
  74 .Sh DESCRIPTION
  75 The function
  76 .Fn timeout
  77 schedules a call to the function given by the argument
  78 .Fa func
  79 to take place after
  80 .Fa ticks Ns No /hz
  81 seconds.
  82 Non-positive values of
  83 .Fa ticks
  84 are silently converted to the value
  85 .Sq 1 .
  86 .Fa func
  87 should be a pointer to a function that takes a
  88 .Fa void *
  89 argument.
  90 Upon invocation,
  91 .Fa func
  92 will receive
  93 .Fa arg
  94 as its only argument.
  95 The return value from
  96 .Fn timeout
  97 is a
  98 .Ft struct callout_handle
  99 which can be used in conjunction with the
 100 .Fn untimeout
 101 function to request that a scheduled timeout be canceled.
 102 .Pp
 103 The function
 104 .Fn callout_handle_init
 105 can be used to initialize a handle to a state which will cause
 106 any calls to
 107 .Fn untimeout
 108 with that handle to return with no side
 109 effects.
 110 .Pp
 111 Assigning a callout handle the value of
 112 .Fn CALLOUT_HANDLE_INITIALIZER
 113 performs the same function as
 114 .Fn callout_handle_init
 115 and is provided for use on statically declared or global callout handles.
 116 .Pp
 117 The function
 118 .Fn untimeout
 119 cancels the timeout associated with
 120 .Fa handle
 121 using the
 122 .Fa func
 123 and
 124 .Fa arg
 125 arguments to validate the handle.
 126 If the handle does not correspond to a timeout with
 127 the function
 128 .Fa func
 129 taking the argument
 130 .Fa arg
 131 no action is taken.
 132 .Fa handle
 133 must be initialized by a previous call to
 134 .Fn timeout ,
 135 .Fn callout_handle_init ,
 136 or assigned the value of
 137 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
 138 before being passed to
 139 .Fn untimeout .
 140 The behavior of calling
 141 .Fn untimeout
 142 without a previously initialized handle
 143 is undefined.
 144 .Pp
 145 As handles are recycled by the system, it is possible (although unlikely)
 146 that a handle from one invocation of
 147 .Fn timeout
 148 may match the handle of another invocation of
 149 .Fn timeout
 150 if both calls used the same function pointer and argument, and the first
 151 timeout is expired or canceled before the second call.
 152 The timeout facility offers O(1) running time for
 153 .Fn timeout
 154 and
 155 .Fn untimeout .
 156 Timeouts are executed from
 157 .Fn softclock
 158 inside a critical section.
 159 Thus they are protected from re-entrancy.
 160 .Pp
 161 The functions
 162 .Fn callout_init ,
 163 .Fn callout_stop
 164 and
 165 .Fn callout_reset
 166 are low-level routines for clients who wish to allocate their own
 167 callout structures.
 168 .Pp
 169 The function
 170 .Fn callout_init
 171 initializes a callout so it can be passed to
 172 .Fn callout_stop
 173 or
 174 .Fn callout_reset
 175 without any side effects.
 176 .Pp
 177 The function
 178 .Fn callout_stop
 179 cancels a callout if it is currently pending.
 180 If the callout is pending, then
 181 .Fn callout_stop
 182 will return a non-zero value.
 183 If the callout has already been serviced or is currently being serviced,
 184 then zero will be returned.
 185 .Pp
 186 The function
 187 .Fn callout_reset
 188 first calls
 189 .Fn callout_stop
 190 to disestablish the callout, and then establishes a new callout in the
 191 same manner as
 192 .Fn timeout .
 193 .Sh RETURN VALUES
 194 The
 195 .Fn timeout
 196 function returns a
 197 .Ft struct callout_handle
 198 that can be passed to
 199 .Fn untimeout .
 200 The
 201 .Fn callout_stop
 202 function returns non-zero if the callout is still pending or zero otherwise.
 203 .Sh HISTORY
 204 The current timeout and untimeout routines are based on the work of
 205 .An Adam M. Costello
 206 and
 207 .An George Varghese ,
 208 published in a technical report entitled
 209 .%T "Redesigning the BSD Callout and Timer Facilities"
 210 and modified slightly for inclusion in
 211 .Fx
 212 by
 213 .An Justin T. Gibbs .
 214 The original work on the data structures used in this implementation
 215 was published by
 216 .An G. Varghese
 217 and
 218 .An A. Lauck
 219 in the paper
 220 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
 221 in the
 222 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
 223 The current implementation replaces the long standing
 224 .Bx
 225 linked list
 226 callout mechanism which offered O(n) insertion and removal running time
 227 but did not generate or require handles for untimeout operations.