From: art Date: Thu, 23 Mar 2000 10:10:20 +0000 (+0000) Subject: Document the new timeout API. X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=b91d1039837350797a32ce293eac2c9a4e15813b;p=openbsd Document the new timeout API. --- diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9 index 4989c7a010d..8659c0780a3 100644 --- a/share/man/man9/timeout.9 +++ b/share/man/man9/timeout.9 @@ -1,91 +1,126 @@ -.\" $OpenBSD: timeout.9,v 1.2 1999/09/02 17:28:07 espie Exp $ -.\" $NetBSD: timeout.9,v 1.7 1999/03/16 00:40:48 garbled Exp $ +.\" $OpenBSD: timeout.9,v 1.3 2000/03/23 10:10:20 art Exp $ .\" -.\" Copyright (c) 1996 The NetBSD Foundation, Inc. -.\" All rights reserved. +.\" Copyright (c) 2000 Artur Grabowski +.\" 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: .\" -.\" 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. +.\" 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. The name of the author may not 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. +.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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 +.Nm timeout_set , +.Nm timeout_add , +.Nm timeout_del .Nd execute a function after a specified length of time .Sh SYNOPSIS .Fd #include -.Fd #include -.Ft void -.Fn "timeout" "void (*ftn)(void *)" "void *arg" "int ticks" -.Ft void -.Fn "untimeout" "void (*ftn)(void *)" "void *arg" +.Fd #include +.Fn "timeout_set" "struct timeout *to" "void (*fn)(void *)" "void *arg" +.Fn "timeout_add" "struct timeout *to" "int ticks" +.Fn "timeout_del" "struct timeout *to" .Sh DESCRIPTION +The finction +.Fn timeout_set +Prepares the timeout structure +.Fa to +to be used in future calls to +.Fn timeout_add +and +.Fn timeout_del . +The timeout will be preapared to call the function given in the +.Fa fn +argument with a +.Fa void * +argument given in the +.Fa arg +argument. +Once initialized, the +.Fa to +structure can be used in repeatedly in +.Fn timeout_add +and +.Fn timeout_del +and doesn't need to be reinitialized unless you wish to +change the function called and/or the argument to it. +.Pp The function -.Fn timeout -schedules a call to the function given by the argument -.Fa ftn -to take place after +.Fn timeout_del +schedules an execution of the +.Fa to +timeout in at least .Fa ticks Ns No /hz seconds. -Non-positive values of +Negative values of .Fa ticks -are silently converted to the value -.Sq 1 . -.Fa ftn -should be a pointer to a function that takes a -.Fa void * -argument, to which the argument -.Fa arg -will be passed. +are illegal. If the value is +.Sq 0 +it will, in the current implementation, be treated as +.Sq 1 +, but in the future it might cause an immediate timeout. +The timeout in the +.Fa to +argument must be already initialized by +.Fn timeout_set +and may not be used in calls to timeout_set until it has +timed out or been removed with +.Fn timeout_del . +If the timeout in the +.Fa to +argument is already scheduled, the old execution time will be +replaced by the new one. .Pp The function -.Fn untimeout -cancels the first scheduled call -.Pq i.e. the one with the shortest delay left -that matches the -.Aq Fa ftn , Ns Fa arg -pair. -If a match can not be found in the callout queue, nothing happens. +.Fn timeout_del +will cancel the timeout in the argument +.Fa to . +If the timeout has already executed or has never been added +the call will have no effect. +.Pp +It's the caller responsibility to provide those functions with +the timeout structures. No functions in this API will do memory +allocation. All functions in this API may be called in interrupt +context below +.Fn splclock . .Pp -The callout queue is statically sized, dependent on the -.Va MAXUSERS -parameter. +The old +.Fn timeout +and +.Fn untimeout +interface is implemented as wrappers around the new API, but it's +obsolete and will be removed in the future. .Sh CODE REFERENCES These functions are implemented in the file -.Pa sys/kern/kern_clock.c . +.Pa sys/kern/kern_timeout.c . .Sh SEE ALSO .Xr hz 9 , .Xr sleep 9 .Sh BUGS -.Fn untimeout -should probably remove all matches from the queue. +The +.Fn timeout_add +function executes in linear speed depending on the number of pending +timeouts. It will also block all interrupts while inserting the timeout +to the timeout queue. Thus it is not recommended to use a large number +of timeouts in the system. +