share/man/man9/timeout.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/Attic/timeout.9,v 1.2 2003/06/17 04:37:01 dillon 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 at
 150 .Fn splsoftclock .
 151 Thus they are protected from re-entrancy.
 152 .Pp
 153 The functions
 154 .Fn callout_init ,
 155 .Fn callout_stop
 156 and
 157 .Fn callout_reset
 158 are low-level routines for clients who wish to allocate their own
 159 callout structures.
 160 .Pp
 161 The function
 162 .Fn callout_init
 163 initializes a callout so it can be passed to
 164 .Fn callout_stop
 165 or
 166 .Fn callout_reset
 167 without any side effects.
 168 .Pp
 169 The function
 170 .Fn callout_stop
 171 cancels a callout if it is currently pending.
 172 If the callout is pending, then
 173 .Fn callout_stop
 174 will return a non-zero value.
 175 If the callout has already been serviced or is currently being serviced,
 176 then zero will be returned.
 177 .Pp
 178 The function
 179 .Fn callout_reset
 180 first calls
 181 .Fn callout_stop
 182 to disestablish the callout, and then establishes a new callout in the
 183 same manner as
 184 .Fn timeout .
 185 .Sh RETURN VALUES
 186 The
 187 .Fn timeout
 188 function returns a
 189 .Ft struct callout_handle
 190 that can be passed to
 191 .Fn untimeout .
 192 The
 193 .Fn callout_stop
 194 function returns non-zero if the callout is still pending or zero otherwise.
 195 .Sh HISTORY
 196 The current timeout and untimeout routines are based on the work of
 197 .An Adam M. Costello
 198 and
 199 .An George Varghese ,
 200 published in a technical report entitled
 201 .%T "Redesigning the BSD Callout and Timer Facilities"
 202 and modified slightly for inclusion in
 203 .Fx
 204 by
 205 .An Justin T. Gibbs .
 206 The original work on the data structures used in this implementation
 207 was published by
 208 .An G. Varghese
 209 and
 210 .An A. Lauck
 211 in the paper
 212 .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility"
 213 in the
 214 .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" .
 215 The current implementation replaces the long standing
 216 .Bx
 217 linked list
 218 callout mechanism which offered O(n) insertion and removal running time
 219 but did not generate or require handles for untimeout operations.