bcebb5ef31
callout lock while the callout is happening. So the serialization that I thought was happening isn't. Therefore, remove the part of the bugs that says this. Leave in the other bug as it is very hard to work around (impossible?). Fix various typos. Also note that timeout/untimeout are considered to be the old interface and the callout interface should be used insetad. Submitted by: bde (first two) and wollman (third)
247 lines
7.3 KiB
Groff
247 lines
7.3 KiB
Groff
.\" $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
|
|
.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
|
|
.In sys/types.h
|
|
.In sys/systm.h
|
|
.Pp
|
|
.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
|
|
.Ft void
|
|
.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
|
|
.Ft void
|
|
.Fn callout_init "struct callout *c" "int mpsafe"
|
|
.Ft int
|
|
.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.
|
|
The
|
|
.Fn timeout
|
|
call is the old style and new code should use the callout_* functions.
|
|
.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.
|
|
The
|
|
.Fn untimeout
|
|
call is the old style and new code should use the callout_* functions.
|
|
.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.
|
|
If the
|
|
.Fa mpsafe
|
|
argument is zero,
|
|
the callout structure is not considered to be
|
|
.Dq multi-processor safe ;
|
|
that is,
|
|
the Giant lock will be acquired before calling the callout function,
|
|
and released when the callout function returns.
|
|
.Pp
|
|
The function
|
|
.Fn callout_stop
|
|
cancels a callout if it is currently pending.
|
|
If the callout is pending, then
|
|
.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.
|
|
.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 .
|
|
The
|
|
.Fn callout_stop
|
|
function returns non-zero if the callout was still pending when it was
|
|
called or zero otherwise.
|
|
.Sh BUGS
|
|
This API has no way to cancel a callout and ensure that if it was
|
|
canceled too late that the callout has actually finished.
|
|
.Fn callout_stop
|
|
only guarantees that the callout has started when it returns 0.
|
|
It does not guarantee that the callout has finished.
|
|
This can create a race when one wishes to ensure that no threads are
|
|
executing before returning from a driver detach routine.
|
|
.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
|
|
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.
|