1258945Sroberto/* 2258945Sroberto * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC") 3258945Sroberto * Copyright (C) 1999-2002 Internet Software Consortium. 4258945Sroberto * 5258945Sroberto * Permission to use, copy, modify, and/or distribute this software for any 6258945Sroberto * purpose with or without fee is hereby granted, provided that the above 7258945Sroberto * copyright notice and this permission notice appear in all copies. 8258945Sroberto * 9258945Sroberto * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10258945Sroberto * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11258945Sroberto * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12258945Sroberto * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13258945Sroberto * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14258945Sroberto * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15258945Sroberto * PERFORMANCE OF THIS SOFTWARE. 16258945Sroberto */ 17258945Sroberto 18280849Scy/* $Id: ratelimiter.h,v 1.23 2009/01/18 23:48:14 tbox Exp $ */ 19258945Sroberto 20258945Sroberto#ifndef ISC_RATELIMITER_H 21258945Sroberto#define ISC_RATELIMITER_H 1 22258945Sroberto 23258945Sroberto/***** 24258945Sroberto ***** Module Info 25258945Sroberto *****/ 26258945Sroberto 27258945Sroberto/*! \file isc/ratelimiter.h 28258945Sroberto * \brief A rate limiter is a mechanism for dispatching events at a limited 29258945Sroberto * rate. This is intended to be used when sending zone maintenance 30258945Sroberto * SOA queries, NOTIFY messages, etc. 31258945Sroberto */ 32258945Sroberto 33258945Sroberto/*** 34258945Sroberto *** Imports. 35258945Sroberto ***/ 36258945Sroberto 37258945Sroberto#include <isc/lang.h> 38258945Sroberto#include <isc/types.h> 39258945Sroberto 40258945SrobertoISC_LANG_BEGINDECLS 41258945Sroberto 42258945Sroberto/***** 43258945Sroberto ***** Functions. 44258945Sroberto *****/ 45258945Sroberto 46258945Srobertoisc_result_t 47258945Srobertoisc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr, 48258945Sroberto isc_task_t *task, isc_ratelimiter_t **ratelimiterp); 49258945Sroberto/*%< 50258945Sroberto * Create a rate limiter. The execution interval is initially undefined. 51258945Sroberto */ 52258945Sroberto 53258945Srobertoisc_result_t 54258945Srobertoisc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval); 55258945Sroberto/*!< 56258945Sroberto * Set the minimum interval between event executions. 57258945Sroberto * The interval value is copied, so the caller need not preserve it. 58258945Sroberto * 59258945Sroberto * Requires: 60258945Sroberto * '*interval' is a nonzero interval. 61258945Sroberto */ 62258945Sroberto 63258945Srobertovoid 64258945Srobertoisc_ratelimiter_setpertic(isc_ratelimiter_t *rl, isc_uint32_t perint); 65258945Sroberto/*%< 66258945Sroberto * Set the number of events processed per interval timer tick. 67258945Sroberto * If 'perint' is zero it is treated as 1. 68258945Sroberto */ 69258945Sroberto 70258945Srobertoisc_result_t 71258945Srobertoisc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task, 72258945Sroberto isc_event_t **eventp); 73258945Sroberto/*%< 74258945Sroberto * Queue an event for rate-limited execution. 75258945Sroberto * 76258945Sroberto * This is similar 77258945Sroberto * to doing an isc_task_send() to the 'task', except that the 78258945Sroberto * execution may be delayed to achieve the desired rate of 79258945Sroberto * execution. 80258945Sroberto * 81258945Sroberto * '(*eventp)->ev_sender' is used to hold the task. The caller 82258945Sroberto * must ensure that the task exists until the event is delivered. 83258945Sroberto * 84258945Sroberto * Requires: 85258945Sroberto *\li An interval has been set by calling 86258945Sroberto * isc_ratelimiter_setinterval(). 87258945Sroberto * 88258945Sroberto *\li 'task' to be non NULL. 89258945Sroberto *\li '(*eventp)->ev_sender' to be NULL. 90258945Sroberto */ 91258945Sroberto 92258945Srobertovoid 93258945Srobertoisc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter); 94258945Sroberto/*%< 95258945Sroberto * Shut down a rate limiter. 96258945Sroberto * 97258945Sroberto * Ensures: 98258945Sroberto *\li All events that have not yet been 99258945Sroberto * dispatched to the task are dispatched immediately with 100258945Sroberto * the #ISC_EVENTATTR_CANCELED bit set in ev_attributes. 101258945Sroberto * 102258945Sroberto *\li Further attempts to enqueue events will fail with 103258945Sroberto * #ISC_R_SHUTTINGDOWN. 104258945Sroberto * 105258945Sroberto *\li The rate limiter is no longer attached to its task. 106258945Sroberto */ 107258945Sroberto 108258945Srobertovoid 109258945Srobertoisc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target); 110258945Sroberto/*%< 111258945Sroberto * Attach to a rate limiter. 112258945Sroberto */ 113258945Sroberto 114258945Srobertovoid 115258945Srobertoisc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp); 116258945Sroberto/*%< 117258945Sroberto * Detach from a rate limiter. 118258945Sroberto */ 119258945Sroberto 120258945Srobertoisc_result_t 121258945Srobertoisc_ratelimiter_stall(isc_ratelimiter_t *rl); 122258945Sroberto/*%< 123258945Sroberto * Stall event processing. 124258945Sroberto */ 125258945Sroberto 126258945Srobertoisc_result_t 127258945Srobertoisc_ratelimiter_release(isc_ratelimiter_t *rl); 128258945Sroberto/*%< 129258945Sroberto * Release a stalled rate limiter. 130258945Sroberto */ 131258945Sroberto 132258945SrobertoISC_LANG_ENDDECLS 133258945Sroberto 134258945Sroberto#endif /* ISC_RATELIMITER_H */ 135