1.\" $NetBSD: rt_timer.9,v 1.8 2002/02/13 08:18:50 ross Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kevin M. Lahey of the Numerical Aerospace Simulation Facility, 8.\" NASA Ames Research Center. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgment: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd April 23, 1998 39.Dt RT_TIMER 9 40.Os 41.Sh NAME 42.Nm rt_timer , 43.Nm rt_timer_add , 44.Nm rt_timer_queue_create , 45.Nm rt_timer_queue_change , 46.Nm rt_timer_queue_destroy , 47.Nm rt_timer_remove_all 48.Nd route callout functions 49.Sh SYNOPSIS 50.Fd #include \*[Lt]net/route.h\*[Gt] 51.Ft "struct rttimer_queue *" 52.Fn rt_timer_queue_create "time_t timeout" 53.Ft void 54.Fn rt_timer_queue_change "struct rttimer_queue *q" "time_t timeout" 55.Ft void 56.Fn rt_timer_queue_destroy "struct rttimer_queue *q" "int destroy" 57.Ft int 58.Fn rt_timer_add "struct rtentry *rt" \ 59"void(*f)(struct rtentry *, struct rttimer *)" "struct rttimer_queue *q" 60.Ft void 61.Fn rt_timer_remove_all "struct rtentry *rt" 62.Sh DESCRIPTION 63The 64.Nm 65functions provide a generic route callout functionality. 66They allow a function to be called for a route at any time. 67This was originally intended to be used to remove routes added 68by path MTU discovery code. 69.Pp 70For maximum efficiency, a separate queue should be defined for each 71timeout period. For example, one queue should be created for the 7210 minute path MTU discovery timeouts, another for 20 minute ARP 73timeouts after 20 minutes, and so on. This permits extremely fast 74queue manipulations so that the timeout functions remain scalable, 75even in the face of thousands of route manipulations per minute. 76.Pp 77It is possible to create only a single timeout queue for all possible 78timeout values, but doing so is not scalable as queue manipulations 79become quite expensive if the timeout deltas are not roughly constant. 80.Pp 81The 82.Nm 83interface provides the following functions: 84.Bl -tag -width compact 85.It Fn rt_timer_queue_create "time_t timeout" 86This function creates a new timer queue with the specified timeout period 87.Fa timeout , 88expressed in seconds. 89.It Fn rt_timer_queue_change "rttimer_queue *q" "time_t timeout" 90This function modifies the timeout period for a timer queue. 91Any value, including 0, is valid. The next time the timer queue's 92timeout expires (based on the previous timeout value), all entries 93which are valid to execute based on the new timeout will be executed, 94and the new timeout period scheduled. 95.It Fn rt_timer_queue_destroy "rttimer_queue *q" "int destroy" 96This function destroys a timeout queue. All entries are removed, 97and if the 98.Fa destroy 99argument is non-zero, the timeout action is performed for each entry. 100.It Fn rt_timer_add "struct rtentry *rt" \ 101"void(*f)(struct rtentry *, struct rttimer *)" "struct rttimer_queue *q" 102This function adds an entry to a timeout queue. 103The function 104.Fa f 105will be called after the timeout period for queue 106.Fa q 107has elapsed. 108If 109.Fa f 110is NULL 111the route will be deleted when the timeout expires. 112.It Fn rt_timer_remove_all "struct rtentry *rt" 113This function removes all references to the given route from the 114.Nm 115subsystem. This is used when a route is deleted to ensure that no 116dangling references remain. 117.El 118.Sh SEE ALSO 119.Xr netstat 1 , 120.Xr arp 9 121.Sh AUTHORS 122This interface is roughly based on (but, alas, not compatible with) one 123designed by David Borman of BSDI. This implementation is by Kevin Lahey 124of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 125.Sh CODE REFERENCES 126The 127.Nm 128interface is implemented in 129.Pa sys/net/route.h 130and 131.Pa sys/net/route.c . 132.Sh HISTORY 133The 134.Nm 135interface appeared in 136.Nx 1.4 . 137