contrib/bind-9.3/lib/isc/include/isc/ratelimiter.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: ratelimiter.h,v 1.13.14.3 2004/03/08 09:04:53 marka Exp $ */
  19
  20 #ifndef ISC_RATELIMITER_H
  21 #define ISC_RATELIMITER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * A rate limiter is a mechanism for dispatching events at a limited
  29  * rate.  This is intended to be used when sending zone maintenance
  30  * SOA queries, NOTIFY messages, etc.
  31  */
  32
  33 /***
  34  *** Imports.
  35  ***/
  36
  37 #include <isc/lang.h>
  38 #include <isc/types.h>
  39
  40 ISC_LANG_BEGINDECLS
  41
  42 /*****
  43  ***** Functions.
  44  *****/
  45
  46 isc_result_t
  47 isc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,
  48                        isc_task_t *task, isc_ratelimiter_t **ratelimiterp);
  49 /*
  50  * Create a rate limiter.  The execution interval is initially undefined.
  51  */
  52
  53 isc_result_t
  54 isc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval);
  55 /*
  56  * Set the mininum interval between event executions.
  57  * The interval value is copied, so the caller need not preserve it.
  58  *
  59  * Requires:
  60  *      '*interval' is a nonzero interval.
  61  */
  62
  63 void
  64 isc_ratelimiter_setpertic(isc_ratelimiter_t *rl, isc_uint32_t perint);
  65 /*
  66  * Set the number of events processed per interval timer tick.
  67  * If 'perint' is zero it is treated as 1.
  68  */
  69
  70 isc_result_t
  71 isc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task,
  72                         isc_event_t **eventp);
  73 /*
  74  * Queue an event for rate-limited execution.  This is similar
  75  * to doing an isc_task_send() to the 'task', except that the
  76  * execution may be delayed to achieve the desired rate of
  77  * execution.
  78  *
  79  * '(*eventp)->ev_sender' is used to hold the task.  The caller
  80  * must ensure that the task exists until the event is delivered.
  81  *
  82  * Requires:
  83  *      An interval has been set by calling
  84  *      isc_ratelimiter_setinterval().
  85  *
  86  *      'task' to be non NULL.
  87  *      '(*eventp)->ev_sender' to be NULL.
  88  */
  89
  90 void
  91 isc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter);
  92 /*
  93  * Shut down a rate limiter.
  94  *
  95  * Ensures:
  96  *      All events that have not yet been
  97  *      dispatched to the task are dispatched immediately with
  98  *      the ISC_EVENTATTR_CANCELED bit set in ev_attributes.
  99  *
 100  *      Further attempts to enqueue events will fail with
 101  *      ISC_R_SHUTTINGDOWN.
 102  *
 103  *      The reatelimiter is no longer attached to its task.
 104  */
 105
 106 void
 107 isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target);
 108 /*
 109  * Attach to a rate limiter.
 110  */
 111
 112 void
 113 isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp);
 114 /*
 115  * Detach from a rate limiter.
 116  */
 117
 118 isc_result_t
 119 isc_ratelimiter_stall(isc_ratelimiter_t *rl);
 120 /*
 121  * Stall event processing.
 122  */
 123
 124 isc_result_t
 125 isc_ratelimiter_release(isc_ratelimiter_t *rl);
 126 /*
 127  * Release a stalled rate limiter.
 128  */
 129
 130 ISC_LANG_ENDDECLS
 131
 132 #endif /* ISC_RATELIMITER_H */