share/man/man9/rt_timer.9

   1 .\"     $NetBSD: rt_timer.9,v 1.10 2003/04/16 13:35:33 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 April 23, 1998
  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
  56 The
  57 .Nm
  58 functions provide a generic route callout functionality.
  59 They allow a function to be called for a route at any time.
  60 This was originally intended to be used to remove routes added
  61 by path MTU discovery code.
  62 .Pp
  63 For maximum efficiency, a separate queue should be defined for each
  64 timeout period.
  65 For example, one queue should be created for the 10 minute path MTU
  66 discovery timeouts, another for 20 minute ARP timeouts after 20
  67 minutes, and so on.
  68 This permits extremely fast queue manipulations so that the timeout
  69 functions remain scalable, even in the face of thousands of route
  70 manipulations per minute.
  71 .Pp
  72 It is possible to create only a single timeout queue for all possible
  73 timeout values, but doing so is not scalable as queue manipulations
  74 become quite expensive if the timeout deltas are not roughly constant.
  75 .Pp
  76 The
  77 .Nm
  78 interface provides the following functions:
  79 .Bl -tag -width compact
  80 .It Fn rt_timer_queue_create "time_t timeout"
  81 This function creates a new timer queue with the specified timeout period
  82 .Fa timeout ,
  83 expressed in seconds.
  84 .It Fn rt_timer_queue_change "rttimer_queue *q" "time_t timeout"
  85 This function modifies the timeout period for a timer queue.
  86 Any value, including 0, is valid.
  87 The next time the timer queue's timeout expires (based on the previous
  88 timeout value), all entries which are valid to execute based on the new
  89 timeout will be executed, and the new timeout period scheduled.
  90 .It Fn rt_timer_queue_destroy "rttimer_queue *q" "int destroy"
  91 This function destroys a timeout queue.
  92 All entries are removed, and if the
  93 .Fa destroy
  94 argument 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"
  97 This function adds an entry to a timeout queue.
  98 The function
  99 .Fa f
 100 will be called after the timeout period for queue
 101 .Fa q
 102 has elapsed.
 103 If
 104 .Fa f
 105 is NULL
 106 the route will be deleted when the timeout expires.
 107 .It Fn rt_timer_remove_all "struct rtentry *rt"
 108 This function removes all references to the given route from the
 109 .Nm
 110 subsystem.
 111 This is used when a route is deleted to ensure that no dangling
 112 references remain.
 113 .El
 114 .Sh SEE ALSO
 115 .Xr netstat 1 ,
 116 .Xr arp 9
 117 .Sh AUTHORS
 118 This interface is roughly based on (but, alas, not compatible with) one
 119 designed by David Borman of BSDI.
 120 This implementation is by Kevin Lahey of the Numerical Aerospace
 121 Simulation Facility, NASA Ames Research Center.
 122 .Sh CODE REFERENCES
 123 The
 124 .Nm
 125 interface is implemented in
 126 .Pa sys/net/route.h
 127 and
 128 .Pa sys/net/route.c .
 129 .Sh HISTORY
 130 The
 131 .Nm
 132 interface appeared in
 133 .Nx 1.4 .