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