2c1bb20746
callout_stop(), except that if the callout being stopped is currently in progress, it blocks attempts to reset the callout and waits until the callout is completed before it returns. This makes it possible to clean up callout-using code safely, e.g., without potentially freeing memory which is still being used by a callout. Reviewed by: mux, gallatin, rwatson, jhb
254 lines
7.3 KiB
Groff
254 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_drain ,
|
|
.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 int
|
|
.Fn callout_drain "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 ,
|
|
.Fn callout_drain
|
|
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 ,
|
|
.Fn callout_drain
|
|
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_drain
|
|
is identical to
|
|
.Fn callout_stop
|
|
except that it will wait for the callout to be completed if it is
|
|
already in progress. This MUST NOT be called while holding any
|
|
locks on which the callout might block, or deadlock will result.
|
|
.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
|
|
and
|
|
.Fn callout_drain
|
|
functions return non-zero if the callout was still pending when it was
|
|
called 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
|
|
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.
|