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

   1 /*
   2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or 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.21.128.2 2009/01/19 23:47:03 tbox Exp $ */
  19
  20 #ifndef ISC_RATELIMITER_H
  21 #define ISC_RATELIMITER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/ratelimiter.h
  28  * \brief 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 minimum 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.
  75  *
  76  * This is similar
  77  * to doing an isc_task_send() to the 'task', except that the
  78  * execution may be delayed to achieve the desired rate of
  79  * execution.
  80  *
  81  * '(*eventp)->ev_sender' is used to hold the task.  The caller
  82  * must ensure that the task exists until the event is delivered.
  83  *
  84  * Requires:
  85  *\li   An interval has been set by calling
  86  *      isc_ratelimiter_setinterval().
  87  *
  88  *\li   'task' to be non NULL.
  89  *\li   '(*eventp)->ev_sender' to be NULL.
  90  */
  91
  92 void
  93 isc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter);
  94 /*%<
  95  * Shut down a rate limiter.
  96  *
  97  * Ensures:
  98  *\li   All events that have not yet been
  99  *      dispatched to the task are dispatched immediately with
 100  *      the #ISC_EVENTATTR_CANCELED bit set in ev_attributes.
 101  *
 102  *\li   Further attempts to enqueue events will fail with
 103  *      #ISC_R_SHUTTINGDOWN.
 104  *
 105  *\li   The rate limiter is no longer attached to its task.
 106  */
 107
 108 void
 109 isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target);
 110 /*%<
 111  * Attach to a rate limiter.
 112  */
 113
 114 void
 115 isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp);
 116 /*%<
 117  * Detach from a rate limiter.
 118  */
 119
 120 isc_result_t
 121 isc_ratelimiter_stall(isc_ratelimiter_t *rl);
 122 /*%<
 123  * Stall event processing.
 124  */
 125
 126 isc_result_t
 127 isc_ratelimiter_release(isc_ratelimiter_t *rl);
 128 /*%<
 129  * Release a stalled rate limiter.
 130  */
 131
 132 ISC_LANG_ENDDECLS
 133
 134 #endif /* ISC_RATELIMITER_H */