From 979d879c6c5d32f7f67f33a12653d1e06ecac1bc Mon Sep 17 00:00:00 2001 From: gibbs Date: Sun, 21 Sep 1997 22:12:19 +0000 Subject: [PATCH] Updated timeout.9 man page describing the new callout interface. This man page was based on the NetBSD version. --- share/man/man9/timeout.9 | 191 +++++++++++++++++++++++++-------------- 1 file changed, 124 insertions(+), 67 deletions(-) diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9 index 11331625305f..a3d1b4d69603 100644 --- a/share/man/man9/timeout.9 +++ b/share/man/man9/timeout.9 @@ -1,8 +1,11 @@ +.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ .\" -.\" Copyright (c) 1996 Joerg Wunsch -.\" +.\" 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: @@ -11,79 +14,133 @@ .\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" 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. .\" -.\" $Id: timeout.9,v 1.4 1997/03/19 03:18:01 bde Exp $ -.\" " -.Dd April 13, 1996 -.Os +.Dd September 10, 1996 .Dt TIMEOUT 9 +.Os FreeBSD .Sh NAME -.Nm timeout , -.Nm untimeout -.Nd schedule timer events -.Sh SYNOPSIS -.Fd #include -.Fd #include -.Ft typedef void timeout_t \*(lpvoid *\*(rp; - -.Ft void -.Fn timeout "timeout_t *func" "void *arg" "int ticks" -.Ft void -.Fn untimeout "timeout_t *func" "void *arg" -.Sh DESCRIPTION -The .Nm timeout -facility allows the execution of a function after a specified amount -of time. The function -.Ar func -is being called with the opaque argument -.Ar arg -after -.Ar ticks -timer ticks have been elapsed. It's often convenient to use the -external variable -.Dv hz -to compute the amount of -.Ar ticks -to wait. +.Nd execute a function after a specified length of time +.Sh SYNOPSIS +typedef void timeout_t \*(lpvoid *\*(rp; + +.Ft struct callout_handle +.Fn "timeout" "void (*func)(void *)" "void *arg" "int ticks" +.Ft void +.Fn callout_handle_init "struct callout_handle *" + +struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle) +.Ft void +.Fn "untimeout" "void (*func)(void *)" "void *arg" "struct callout_handle handle" +.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 it's 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 -If the timeout event should be removed before the timer expires, -.Nm untimeout -must be called with the exact -.Ar func +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 -.Ar arg -arguments as the corresponding call to -.Fn timeout . +.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 -Unlike the functions of -.Xr sleep 9 , +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 -can be called from within an interrupt context. -.Sh SEE ALSO -.Xr sleep 9 +.Fn untimeout . +Timeouts are executed from +.Fn softclock +at spl0 and are protected from re-entrancy. .Sh HISTORY -The -.Nm timeout -facility is very old. -.Sh BUGS -Since the timer queue is sorted and uses time differences rather than -absolute times, inserting and removing timer events can be costly if -it is done too frequently. -.Sh AUTHORS -This man page has been written by -.ie t J\(:org Wunsch. -.el Joerg Wunsch. +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.