Updated timeout.9 man page describing the new callout interface. This
man page was based on the NetBSD version.
This commit is contained in:
gibbs
parent
df1f24e6bb
commit
979d879c6c
@ -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 <sys/types.h>
|
||||
.Fd #include <sys/systm.h>
|
||||
.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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user