Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / isc / include / isc / ratelimiter.h
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.21.128.2 2009/01/19 23:47:03 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
40 ISC_LANG_BEGINDECLS
41
42 /*****
43  ***** Functions.
44  *****/
45
46 isc_result_t
47 isc_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
53 isc_result_t
54 isc_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
63 void
64 isc_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
70 isc_result_t
71 isc_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
92 void
93 isc_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
108 void
109 isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target);
110 /*%<
111  * Attach to a rate limiter.
112  */
113
114 void
115 isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp);
116 /*%<
117  * Detach from a rate limiter.
118  */
119
120 isc_result_t
121 isc_ratelimiter_stall(isc_ratelimiter_t *rl);
122 /*%<
123  * Stall event processing.
124  */
125
126 isc_result_t
127 isc_ratelimiter_release(isc_ratelimiter_t *rl);
128 /*%<
129  * Release a stalled rate limiter.
130  */
131
132 ISC_LANG_ENDDECLS
133
134 #endif /* ISC_RATELIMITER_H */