--- src/share/man/man9/callout.9	2007/03/11 20:04:18	1.4
+++ src/share/man/man9/callout.9	2007/11/14 18:27:52	1.5
@@ -37,16 +37,17 @@
 .\" $FreeBSD: src/share/man/man9/timeout.9,v 1.9.2.6 2001/12/17 11:30:19 ru Exp $
 .\" $DragonFly$
 .\"
-.Dd March 11, 2007
-.Dt TIMEOUT 9
+.Dd November 14, 2007
+.Dt CALLOUT 9
 .Os
 .Sh NAME
-.Nm timeout ,
-.Nm untimeout ,
-.Nm callout_handle_init ,
 .Nm callout_init ,
+.Nm callout_init_mp ,
+.Nm callout_reset ,
 .Nm callout_stop ,
-.Nm callout_reset
+.Nm callout_active ,
+.Nm callout_pending ,
+.Nm callout_deactivate
 .Nd execute a function after a specified length of time
 .Sh SYNOPSIS
 .In sys/types.h
@@ -55,173 +56,109 @@
 .Bd -literal
 typedef void timeout_t (void *);
 .Ed
-.Ft struct callout_handle
-.Fn timeout "timeout_t *func" "void *arg" "int ticks"
 .Ft void
-.Fn callout_handle_init "struct callout_handle *handle"
-.Pp
-.Bd -literal
-struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle)
-.Ed
+.Fn callout_init "struct callout *c"
 .Ft void
-.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
+.Fn callout_init_mp "struct callout *c"
 .Ft void
-.Fn callout_init "struct callout *c"
+.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
 .Ft int
 .Fn callout_stop "struct callout *c"
-.Ft void
-.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
+.Ft int
+.Fn callout_active "struct callout *c"
+.Ft int
+.Fn callout_pending "struct callout *c"
+.Fn callout_deactivate "struct callout *c"
 .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
-.Fn 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
-.Fn 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
+The
+.Nm callout
+facility provides a mechanism to execute a function at a given time.
+The timer is based on the hardclock timer which ticks
+.Dv hz
+times per second.
+.Pp
+Clients of the
+.Nm callout
+facility are responsible for providing pre-allocated callout structures, or
+.Dq handles .
+The
+.Nm callout
+facility replaces the historic
+.Bx
+functions
 .Fn timeout
 and
 .Fn untimeout .
-Timeouts are executed from
-.Fn softclock
-inside a critical section.
-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
+The
 .Fn callout_init
-initializes a callout so it can be passed to
+function initializes the callout handle
+.Fa c
+so it can be passed to
 .Fn callout_stop
 or
 .Fn callout_reset
 without any side effects.
+The MP version of this function,
+.Fn callout_init_mp ,
+requires that the callback function installed by
+.Fn callout_reset
+be MP safe.
+.Pp
+The
+.Fn callout_reset
+function resets and starts the timer associated with the callout handle
+.Fa c .
+When the timer expires after
+.Fa ticks Ns No /hz
+seconds, the function specified by
+.Fa func
+will be called with the argument
+.Fa arg .
 .Pp
 The function
 .Fn callout_stop
-cancels a callout if it is currently pending.
-If the callout is pending, then
+cancels the callout associated with the callout handle
+.Fa c
+if it is currently pending.
+It is safe to call
 .Fn callout_stop
-will return a non-zero value.
-If the callout has already been serviced or is currently being serviced,
-then zero will be returned.
+on a callout that is not pending, so long as it is initialized.
+If the callout is not set, has already been serviced or is currently
+being serviced, then zero will be returned.
 .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 RETURN VALUES
 The
-.Fn timeout
-function returns a
-.Ft struct callout_handle
-that can be passed to
-.Fn untimeout .
+.Fn callout_pending
+macro tests if the callout handle
+.Fa c
+is pending.
+A pending callout is one that has been started and whose function has not
+yet been called.
+.Pp
 The
-.Fn callout_stop
-function returns non-zero if the callout is still pending or zero otherwise.
-.Sh HISTORY
-The current timeout and untimeout routines are based on the work of
-.An Adam M. Costello
-and
-.An George Varghese ,
-published in a technical report entitled
-.%T "Redesigning the BSD Callout and Timer Facilities"
-and modified slightly for inclusion in
-.Fx
-by
-.An Justin T. Gibbs .
-The original work on the data structures used in this implementation
-was published by
-.An G. Varghese
+.Fn callout_active
+macro returns true if a timer has been started but not explicitly stopped,
+even if it has already fired.
+.Pp
+The
+.Fn callout_deactivate
+macro deactivates the specified callout
+.Fa c .
+.Pp
+The
+.Fn callout_active ,
+.Fn callout_pending
 and
-.An 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
-.Bx
-linked list
-callout mechanism which offered O(n) insertion and removal running time
-but did not generate or require handles for untimeout operations.
+.Fn callout_deactivate
+macros may only be used when the state of the callout structure is stable,
+meaning from within the callback function or after the callback function
+has been called but the timer has not yet been reset.
+.Sh RETURN VALUES
+The
+.Fn callout_stop
+function and the
+.Fn callout_pending
+macro return non-zero if the callout is still pending or zero otherwise.
+The
+.Fn callout_active
+macro returns non-zero if the callout is active or zero otherwise.