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