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