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