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.23 2009/01/18 23:48:14 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 */ 135