.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 10, 1996 .Dt TIMEOUT 9 .Os FreeBSD .Sh NAME .Nm timeout , .Nm untimeout , .Nm callout_handle_init , .Nm callout_init , .Nm callout_stop , .Nm callout_reset .Nd execute a function after a specified length of time .Sh SYNOPSIS .Fd #include .Fd #include .Ft typedef void timeout_t \*(lpvoid *\*(rp; .Ft struct callout_handle .Fn timeout "timeout_t *func" "void *arg" "int ticks" .Ft void .Fn callout_handle_init "struct callout_handle *handle" .Li struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle) .Ft void .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" .Ft void .Fn callout_init "struct callout *c" .Ft void .Fn callout_stop "struct callout *c" .Ft void .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" .Sh DESCRIPTION The function .Fn timeout schedules a call to the function given by the argument .Fa func to take place after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Fa func should be a pointer to a function that takes a .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The return value from .Fn timeout is a .Ft struct callout_handle which can be used in conjunction with the .Fn untimeout function to request that a scheduled timeout be canceled. .Pp The function .Fn callout_handle_init can be used to initialize a handle to a state which will cause any calls to untimeout with that handle to return with no side effects. .Pp Assigning a callout handle the value of .Fn CALLOUT_HANDLE_INITIALIZER performs the same function as .Fn callout_handle_init and is provided for use on statically declared or global callout handles. .Pp The function .Fn untimeout cancels the timeout associated with .Fa handle using the .Fa func and .Fa arg arguments to validate the handle. If the handle does not correspond to a timeout with the function .Fa func taking the argument .Fa arg no action is taken. .Fa handle must be initialized by a previous call to .Fn timeout , .Fn callout_handle_init , or assigned the value of .Fn CALLOUT_HANDLE_INITIALIZER "&handle" before being passed to .Fn untimeout . The behavior of calling untimeout without a previously initialized handle is undefined. .Pp As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of .Fn timeout may match the handle of another invocation of .Fn timeout if both calls used the same function pointer and argument, and the first timeout is expired or canceled before the second call. The timeout facility offers O(1) running time for .Fn timeout and .Fn untimeout . Timeouts are executed from .Fn softclock at .Fn splsoftclock . Thus they are protected from re-entrancy. .Pp The functions .Fn callout_init , .Fn callout_stop and .Fn callout_reset are low-level routines for clients who wish to allocate their own callout structures. .Pp The function .Fn callout_init initializes a callout so it can be passed to .Fn callout_stop or .Fn callout_reset without any side effects. .Pp The function .Fn callout_stop cancels a callout if it is currently pending. .Pp The function .Fn callout_reset first calls .Fn callout_stop to disestablish the callout, and then establishes a new callout in the same manner as .Fn timeout . .Sh HISTORY The current timeout and untimeout routines are based on the work of Adam M. Costello and George Varghese, published in a technical report entitled .%T "Redesigning the BSD Callout and Timer Facilities" and modified slightly for inclusion in FreeBSD by Justin T. Gibbs. The original work on the data structures used in this implementation was published by G.Varghese and A. Lauck in the paper .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" in the .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . The current implementation replaces the long standing BSD linked list callout mechanism which offered O(n) insertion and removal running time but did not generate or require handles for untimeout operations.