Updated timeout.9 man page describing the new callout interface. This

man page was based on the NetBSD version.

1 files changed, 120 insertions, 63 deletions

diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9
index 1133162..a3d1b4d 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
+.Nm timeout
+.Nd execute a function after a specified length of time
 .Sh SYNOPSIS
-.Fd #include <sys/types.h>
-.Fd #include <sys/systm.h>
-.Ft typedef void timeout_t \*(lpvoid *\*(rp;
+typedef void timeout_t \*(lpvoid *\*(rp;
 
+.Ft struct callout_handle
+.Fn "timeout" "void (*func)(void *)" "void *arg" "int ticks"
 .Ft void
-.Fn timeout "timeout_t *func" "void *arg" "int ticks"
+.Fn callout_handle_init "struct callout_handle *"
+
+struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
 .Ft void
-.Fn untimeout "timeout_t *func" "void *arg"
+.Fn "untimeout" "void (*func)(void *)" "void *arg" "struct callout_handle handle"
 .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.
+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.