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