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