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