1135446Strhodes/* 2193149Sdougb * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC") 3135446Strhodes * Copyright (C) 1999-2002 Internet Software Consortium. 4135446Strhodes * 5193149Sdougb * Permission to use, copy, modify, and/or distribute this software for any 6135446Strhodes * purpose with or without fee is hereby granted, provided that the above 7135446Strhodes * copyright notice and this permission notice appear in all copies. 8135446Strhodes * 9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11135446Strhodes * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes * PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes */ 17135446Strhodes 18234010Sdougb/* $Id: ratelimiter.h,v 1.23 2009/01/18 23:48:14 tbox Exp $ */ 19135446Strhodes 20135446Strhodes#ifndef ISC_RATELIMITER_H 21135446Strhodes#define ISC_RATELIMITER_H 1 22135446Strhodes 23135446Strhodes/***** 24135446Strhodes ***** Module Info 25135446Strhodes *****/ 26135446Strhodes 27193149Sdougb/*! \file isc/ratelimiter.h 28170222Sdougb * \brief A rate limiter is a mechanism for dispatching events at a limited 29135446Strhodes * rate. This is intended to be used when sending zone maintenance 30135446Strhodes * SOA queries, NOTIFY messages, etc. 31135446Strhodes */ 32135446Strhodes 33135446Strhodes/*** 34135446Strhodes *** Imports. 35135446Strhodes ***/ 36135446Strhodes 37135446Strhodes#include <isc/lang.h> 38135446Strhodes#include <isc/types.h> 39135446Strhodes 40135446StrhodesISC_LANG_BEGINDECLS 41135446Strhodes 42135446Strhodes/***** 43135446Strhodes ***** Functions. 44135446Strhodes *****/ 45135446Strhodes 46135446Strhodesisc_result_t 47135446Strhodesisc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr, 48135446Strhodes isc_task_t *task, isc_ratelimiter_t **ratelimiterp); 49170222Sdougb/*%< 50135446Strhodes * Create a rate limiter. The execution interval is initially undefined. 51135446Strhodes */ 52135446Strhodes 53135446Strhodesisc_result_t 54135446Strhodesisc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval); 55170222Sdougb/*!< 56193149Sdougb * Set the minimum interval between event executions. 57135446Strhodes * The interval value is copied, so the caller need not preserve it. 58135446Strhodes * 59135446Strhodes * Requires: 60135446Strhodes * '*interval' is a nonzero interval. 61135446Strhodes */ 62135446Strhodes 63135446Strhodesvoid 64135446Strhodesisc_ratelimiter_setpertic(isc_ratelimiter_t *rl, isc_uint32_t perint); 65170222Sdougb/*%< 66135446Strhodes * Set the number of events processed per interval timer tick. 67135446Strhodes * If 'perint' is zero it is treated as 1. 68135446Strhodes */ 69135446Strhodes 70135446Strhodesisc_result_t 71135446Strhodesisc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task, 72135446Strhodes isc_event_t **eventp); 73170222Sdougb/*%< 74193149Sdougb * Queue an event for rate-limited execution. 75170222Sdougb * 76170222Sdougb * This is similar 77135446Strhodes * to doing an isc_task_send() to the 'task', except that the 78135446Strhodes * execution may be delayed to achieve the desired rate of 79135446Strhodes * execution. 80135446Strhodes * 81135446Strhodes * '(*eventp)->ev_sender' is used to hold the task. The caller 82135446Strhodes * must ensure that the task exists until the event is delivered. 83135446Strhodes * 84135446Strhodes * Requires: 85170222Sdougb *\li An interval has been set by calling 86135446Strhodes * isc_ratelimiter_setinterval(). 87135446Strhodes * 88170222Sdougb *\li 'task' to be non NULL. 89170222Sdougb *\li '(*eventp)->ev_sender' to be NULL. 90135446Strhodes */ 91135446Strhodes 92135446Strhodesvoid 93135446Strhodesisc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter); 94170222Sdougb/*%< 95135446Strhodes * Shut down a rate limiter. 96135446Strhodes * 97135446Strhodes * Ensures: 98170222Sdougb *\li All events that have not yet been 99135446Strhodes * dispatched to the task are dispatched immediately with 100170222Sdougb * the #ISC_EVENTATTR_CANCELED bit set in ev_attributes. 101135446Strhodes * 102170222Sdougb *\li Further attempts to enqueue events will fail with 103170222Sdougb * #ISC_R_SHUTTINGDOWN. 104135446Strhodes * 105193149Sdougb *\li The rate limiter is no longer attached to its task. 106135446Strhodes */ 107135446Strhodes 108135446Strhodesvoid 109135446Strhodesisc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target); 110170222Sdougb/*%< 111135446Strhodes * Attach to a rate limiter. 112135446Strhodes */ 113135446Strhodes 114135446Strhodesvoid 115135446Strhodesisc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp); 116170222Sdougb/*%< 117135446Strhodes * Detach from a rate limiter. 118135446Strhodes */ 119135446Strhodes 120135446Strhodesisc_result_t 121135446Strhodesisc_ratelimiter_stall(isc_ratelimiter_t *rl); 122170222Sdougb/*%< 123135446Strhodes * Stall event processing. 124135446Strhodes */ 125135446Strhodes 126135446Strhodesisc_result_t 127135446Strhodesisc_ratelimiter_release(isc_ratelimiter_t *rl); 128170222Sdougb/*%< 129135446Strhodes * Release a stalled rate limiter. 130135446Strhodes */ 131135446Strhodes 132135446StrhodesISC_LANG_ENDDECLS 133135446Strhodes 134135446Strhodes#endif /* ISC_RATELIMITER_H */ 135