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
40ISC_LANG_BEGINDECLS
41
42/*****
43 ***** Functions.
44 *****/
45
46isc_result_t
47isc_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
53isc_result_t
54isc_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
63void
64isc_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
70isc_result_t
71isc_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
92void
93isc_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
108void
109isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target);
110/*%<
111 * Attach to a rate limiter.
112 */
113
114void
115isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp);
116/*%<
117 * Detach from a rate limiter.
118 */
119
120isc_result_t
121isc_ratelimiter_stall(isc_ratelimiter_t *rl);
122/*%<
123 * Stall event processing.
124 */
125
126isc_result_t
127isc_ratelimiter_release(isc_ratelimiter_t *rl);
128/*%<
129 * Release a stalled rate limiter.
130 */
131
132ISC_LANG_ENDDECLS
133
134#endif /* ISC_RATELIMITER_H */
135