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 September 10, 1996
  40 .Dt TIMEOUT 9
  41 .Os
  42 .Sh NAME
  43 .Nm timeout
  44 .Nd execute a function after a specified length of time
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/systm.h
  48 .Pp
  49 .Bd -literal
  50 typedef void timeout_t (void *);
  51 .Ed
  52 .Ft struct callout_handle
  53 .Fn timeout "timeout_t *func" "void *arg" "int ticks"
  54 .Ft void
  55 .Fn callout_handle_init "struct callout_handle *handle"
  56 .Pp
  57 .Bd -literal
  58 struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
  59 .Ed
  60 .Ft void
  61 .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
  62 .Ft void
  63 .Fn callout_init "struct callout *c"
  64 .Ft int
  65 .Fn callout_stop "struct callout *c"
  66 .Ft void
  67 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
  68 .Sh DESCRIPTION
  69 The function
  70 .Fn timeout
  71 schedules a call to the function given by the argument
  72 .Fa func
  73 to take place after
  74 .Fa ticks Ns No /hz
  75 seconds.
  76 Non-positive values of
  77 .Fa ticks
  78 are silently converted to the value
  79 .Sq 1 .
  80 .Fa func
  81 should be a pointer to a function that takes a
  82 .Fa void *
  83 argument.
  84 Upon invocation,
  85 .Fa func
  86 will receive
  87 .Fa arg
  88 as its only argument.
  89 The return value from
  90 .Fn timeout
  91 is a
  92 .Ft struct callout_handle
  93 which can be used in conjunction with the
  94 .Fn untimeout
  95 function to request that a scheduled timeout be canceled.
  96 .Pp
  97 The function
  98 .Fn callout_handle_init
  99 can be used to initialize a handle to a state which will cause
 100 any calls to untimeout with that handle to return with no side
 101 effects.
 102 .Pp
 103 Assigning a callout handle the value of
 104 .Fn CALLOUT_HANDLE_INITIALIZER
 105 performs the same function as
 106 .Fn callout_handle_init
 107 and is provided for use on statically declared or global callout handles.
 108 .Pp
 109 The function
 110 .Fn untimeout
 111 cancels the timeout associated with
 112 .Fa handle
 113 using the
 114 .Fa func
 115 and
 116 .Fa arg
 117 arguments to validate the handle.
 118 If the handle does not correspond to a timeout with
 119 the function
 120 .Fa func
 121 taking the argument
 122 .Fa arg
 123 no action is taken.
 124 .Fa handle
 125 must be initialized by a previous call to
 126 .Fn timeout ,
 127 .Fn callout_handle_init ,
 128 or assigned the value of
 129 .Fn CALLOUT_HANDLE_INITIALIZER "&handle"
 130 before being passed to
 131 .Fn untimeout .
 132 The behavior of calling untimeout without a previously initialized handle
 133 is undefined.
 134 .Pp
 135 As handles are recycled by the system, it is possible (although unlikely)
 136 that a handle from one invocation of
 137 .Fn timeout
 138 may match the handle of another invocation of
 139 .Fn timeout
 140 if both calls used the same function pointer and argument, and the first
 141 timeout is expired or canceled before the second call.
 142 The timeout facility offers O(1) running time for
 143 .Fn timeout
 144 and
 145 .Fn untimeout .
 146 Timeouts are executed from
 147 .Fn softclock
 148 at
 149 .Fn splsoftclock .
 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.