2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2002 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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.
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.
18 /* $Id: ratelimiter.h,v 1.13.14.3 2004/03/08 09:04:53 marka Exp $ */
20 #ifndef ISC_RATELIMITER_H
21 #define ISC_RATELIMITER_H 1
28 * 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.
38 #include <isc/types.h>
47 isc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,
48 isc_task_t *task, isc_ratelimiter_t **ratelimiterp);
50 * Create a rate limiter. The execution interval is initially undefined.
54 isc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval);
56 * Set the mininum interval between event executions.
57 * The interval value is copied, so the caller need not preserve it.
60 * '*interval' is a nonzero interval.
64 isc_ratelimiter_setpertic(isc_ratelimiter_t *rl, isc_uint32_t perint);
66 * Set the number of events processed per interval timer tick.
67 * If 'perint' is zero it is treated as 1.
71 isc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task,
72 isc_event_t **eventp);
74 * Queue an event for rate-limited execution. This is similar
75 * to doing an isc_task_send() to the 'task', except that the
76 * execution may be delayed to achieve the desired rate of
79 * '(*eventp)->ev_sender' is used to hold the task. The caller
80 * must ensure that the task exists until the event is delivered.
83 * An interval has been set by calling
84 * isc_ratelimiter_setinterval().
86 * 'task' to be non NULL.
87 * '(*eventp)->ev_sender' to be NULL.
91 isc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter);
93 * Shut down a rate limiter.
96 * All events that have not yet been
97 * dispatched to the task are dispatched immediately with
98 * the ISC_EVENTATTR_CANCELED bit set in ev_attributes.
100 * Further attempts to enqueue events will fail with
101 * ISC_R_SHUTTINGDOWN.
103 * The reatelimiter is no longer attached to its task.
107 isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target);
109 * Attach to a rate limiter.
113 isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp);
115 * Detach from a rate limiter.
119 isc_ratelimiter_stall(isc_ratelimiter_t *rl);
121 * Stall event processing.
125 isc_ratelimiter_release(isc_ratelimiter_t *rl);
127 * Release a stalled rate limiter.
132 #endif /* ISC_RATELIMITER_H */