[src/trunk]: src/share/man/man9 Documentation for new callout interfaces.

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/share/man/man9 Documentation for new callout interfaces.
From: thorpej <thorpej%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 06:54:09 +0000
details:   https://anonhg.NetBSD.org/src/rev/e95b0fdb6047
branches:  trunk
changeset: 484019:e95b0fdb6047
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Thu Mar 23 07:05:30 2000 +0000

description:
Documentation for new callout interfaces.

diffstat:

 share/man/man9/Makefile  |   17 ++-
 share/man/man9/callout.9 |  201 +++++++++++++++++++++++++++++++++++++++++++++++
 share/man/man9/timeout.9 |   82 -------------------
 3 files changed, 211 insertions(+), 89 deletions(-)

diffs (truncated from 335 to 300 lines):

diff -r 0291c5311afc -r e95b0fdb6047 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Thu Mar 23 07:04:42 2000 +0000
+++ b/share/man/man9/Makefile   Thu Mar 23 07:05:30 2000 +0000
@@ -1,15 +1,15 @@
-#       $NetBSD: Makefile,v 1.57 2000/02/03 23:03:14 cgd Exp $
+#       $NetBSD: Makefile,v 1.58 2000/03/23 07:05:30 thorpej Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
-MAN=   access.9 arp.9 audio.9 bus_space.9 bus_dma.9 copy.9 cpu_reboot.9 \
-       ctxsw.9 disk.9 disklabel.9 dopowerhooks.9 doshutdownhooks.9 \
-       ethersubr.9 extent.9 fetch.9 fork1.9 humanize_number.9 \
-       inittodr.9 intro.9 ioctl.9 kprintf.9 \
+MAN=   access.9 arp.9 audio.9 bus_dma.9 bus_space.9 callout.9 copy.9 \
+       cpu_reboot.9 ctxsw.9 disk.9 disklabel.9 dopowerhooks.9 \
+       doshutdownhooks.9 ethersubr.9 extent.9 fetch.9 fork1.9 \
+       humanize_number.9 inittodr.9 intro.9 ioctl.9 kprintf.9 \
        log.9 malloc.9 mbuf.9 microtime.9 panic.9 pfil.9 physio.9 pool.9 \
        powerhook_establish.9 psignal.9 ratecheck.9 resettodr.9 rnd.9 \
        rt_timer.9 shutdownhook_establish.9 \
-       sleep.9 spl.9 store.9 time.9 timeout.9 uiomove.9 usbdi.9 uvm.9 \
+       sleep.9 spl.9 store.9 time.9 uiomove.9 usbdi.9 uvm.9 \
        wdc.9
 MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9
 MLINKS+=access.9 kernacc.9 access.9 useracc.9
@@ -51,6 +51,10 @@
        bus_dma.9 bus_dmamem_alloc.9 bus_dma.9 bus_dmamem_free.9 \
        bus_dma.9 bus_dmamem_map.9 bus_dma.9 bus_dmamem_unmap.9 \
        bus_dma.9 bus_dmamem_mmap.9
+MLINKS+=callout.9 callout_init.9 callout.9 callout_reset.9 \
+       callout.9 callout_stop.9 callout.9 callout_active.9 \
+       callout.9 callout_pending.9 callout.9 callout_deactivate.9 \
+       callout.9 timeout.9 callout.9 untimeout.9
 MLINKS+=copy.9 copyin.9 copy.9 copyout.9 copy.9 copystr.9 \
        copy.9 copyinstr.9 copy.9 copyoutstr.9
 MLINKS+=ctxsw.9 cpu_switch.9 ctxsw.9 mi_switch.9
@@ -104,7 +108,6 @@
 MLINKS+=store.9 subyte.9 store.9 suibyte.9 store.9 susword.9 \
        store.9 suswintr.9 store.9 suword.9 store.9 suiword.9
 MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9
-MLINKS+=timeout.9 untimeout.9
 MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \
        uvm.9 uvm_swap_init.9 uvm.9 uvm_map.9 uvm.9 uvm_map_pageable.9 \
        uvm.9 uvm_map_checkprot.9 uvm.9 uvm_map_protect.9 \
diff -r 0291c5311afc -r e95b0fdb6047 share/man/man9/callout.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/callout.9  Thu Mar 23 07:05:30 2000 +0000
@@ -0,0 +1,201 @@
+.\"    $NetBSD: callout.9,v 1.1 2000/03/23 07:05:30 thorpej Exp $
+.\"
+.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jason R. Thorpe.
+.\"
+.\" 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 FOUNDATION 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.
+.\"
+.Dd March 21, 2000
+.Dt CALLOUT 9
+.Os
+.Sh NAME
+.Nm callout_init ,
+.Nm callout_reset ,
+.Nm callout_stop
+.Nd execute a function after a specified length of time
+.Sh SYNOPSIS
+.Ft void
+.Fn "callout_init" "struct callout *c"
+.Ft void
+.Fn "callout_reset" "struct callout *c" "int ticks" \
+    "void (*func)(void *)" "void *arg"
+.Ft void
+.Fn "callout_stop" "struct callout *c"
+.Ft int
+.Fn "callout_active" "struct callout *c"
+.Ft int
+.Fn "callout_pending" "struct callout *c"
+.Ft int
+.Fn "callout_expired" "struct callout *c"
+.Ft void
+.Fn "callout_deactivate" "struct callout *c"
+.Sh DESCRIPTION
+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.  The function is called at softclock interrupt level.
+.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 .
+.Pp
+The
+.Fn callout_init
+function initializes the callout handle
+.Fa c
+for use.  If it is inconvenient to call
+.Fn callout_init ,
+statically-allocated callout handles may be initialized by assigning
+the value
+.Dv CALLOUT_INITIALIZER
+to them.
+.Pp
+The
+.Fn callout_reset
+function starts (or resets) 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 .
+Note that if the timer associated with the callout handle is already running,
+it will be implicitly stopped before being reset.
+Once the timer is started, the callout handle is marked as
+.Em ACTIVE 
+and
+.Em PENDING .
+Once the timer expires,
+.Em PENDING
+status is cleared.  Expiration of the timer does not affect
+.Em ACTIVE
+status.
+.Pp
+The
+.Fn callout_stop
+function stops the timer associated the callout handle
+.Fa c .
+The
+.Em ACTIVE
+and
+.Em PENDING
+status for the callout handle is cleared.  It is safe to call
+.Fn callout_stop
+on a callout handle that is not active, so long as it is initialized.
+.Pp
+The
+.Fn callout_active
+function tests the
+.Em ACTIVE
+status of the callout handle
+.Fa c .
+An
+.Em ACTIVE
+callout is one that has been started but not explicitly stopped.
+Testing
+.Em ACTIVE
+status is a way to determine if a callout has been started.  Once the
+callout fires, the executed function may clear
+.Em ACTIVE
+status.  See
+.Fn callout_deactivate
+below.
+.Pp
+The
+.Fn callout_pending
+function tests the
+.Em PENDING
+status of the callout handle
+.Fa c .
+A
+.Em PENDING
+callout is one that has been started and whose function has not yet
+been called.  Note that it is possible for a callout's timer to have
+expired without its function being called if interrupt level has not
+dropped low enough to let softclock interrupts through.  Note that it
+is only safe to test
+.Em PENDING
+status when at softclock interrupt level or higher.
+.Pp
+The
+.Fn callout_expired
+function tests the opposite of
+.Fn callout_pending .
+That is to say that
+.Fn callout_expired
+returns true when the callout function has been called.
+.Pp
+The
+.Fn callout_deactivate
+function clears the
+.Em ACTIVE
+status of the callout handle
+.Fa c .
+Note that is only safe to call
+.Fn callout_deactivate
+if the callout function has already been executed, i.e. the callout
+is no longer
+.Em PENDING .
+.Sh SEE ALSO
+.Xr hz 9
+.Sh HISTORY
+The
+.Nm callout
+facility is based on the work of Adam M. Costello and George Varghese,
+published in a technical report entitled
+.Dq Redesigning the BSD Callout and Timer Facilities ,
+and Justin Gibbs's subsequent integration into
+.Fx .
+It was modified for
+.Nx
+by Jason R. Thorpe, who also added optional statistics gathering and
+an alternate sorting mode for the callwheel.
+.Pp
+The original work on the data structures used in this implementation was
+published by G. Varghese and A. Lauck in the paper
+Hashed and Hierarchical Timing Wheels: Data Structures for the
+Efficient Implementation of a Timer Facility
+in the Proceedings of the 11th ACM Annual Symposium on Operating System
+Principles, Austin, Texas, November 1987.
diff -r 0291c5311afc -r e95b0fdb6047 share/man/man9/timeout.9
--- a/share/man/man9/timeout.9  Thu Mar 23 07:04:42 2000 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,82 +0,0 @@
-.\"    $NetBSD: timeout.9,v 1.7 1999/03/16 00:40:48 garbled 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 FOUNDATION 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.
-.\"
-.Dd June 23, 1996
-.Dt TIMEOUT 9
-.Os
-.Sh NAME
-.Nm timeout ,
-.Nm untimeout
-.Nd execute a function after a specified length of time
-.Sh SYNOPSIS
-.Ft void
-.Fn "timeout" "void (*fnt)(void *)" "void *arg" "int ticks"
-.Ft void
Prev by Date: [src/trunk]: src/distrib/sets/lists/comp callout.9 pages.
Next by Date: [src/trunk]: src/sys/arch/cobalt/cobalt - Have physical address for MIPS_PHYS...
Previous by Thread: [src/trunk]: src/distrib/sets/lists/comp callout.9 pages.
Next by Thread: [src/trunk]: src/sys/arch/cobalt/cobalt - Have physical address for MIPS_PHYS...
Indexes:
Home | Main Index | Thread Index | Old Index