/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_RATELIMITER_H

[12] Fix | Delete

#define ISC_RATELIMITER_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file isc/ratelimiter.h

[19] Fix | Delete

* \brief A rate limiter is a mechanism for dispatching events at a limited

[20] Fix | Delete

* rate. This is intended to be used when sending zone maintenance

[21] Fix | Delete

* SOA queries, NOTIFY messages, etc.

[22] Fix | Delete

*/

[23] Fix | Delete

[24] Fix | Delete

/***

[25] Fix | Delete

*** Imports.

[26] Fix | Delete

***/

[27] Fix | Delete

[28] Fix | Delete

#include <inttypes.h>

[29] Fix | Delete

#include <stdbool.h>

[30] Fix | Delete

[31] Fix | Delete

#include <isc/lang.h>

[32] Fix | Delete

#include <isc/types.h>

[33] Fix | Delete

[34] Fix | Delete

ISC_LANG_BEGINDECLS

[35] Fix | Delete

[36] Fix | Delete

/*****

[37] Fix | Delete

***** Functions.

[38] Fix | Delete

*****/

[39] Fix | Delete

[40] Fix | Delete

isc_result_t

[41] Fix | Delete

isc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,

[42] Fix | Delete

isc_task_t *task, isc_ratelimiter_t **ratelimiterp);

[43] Fix | Delete

/*%<

[44] Fix | Delete

* Create a rate limiter. The execution interval is initially undefined.

[45] Fix | Delete

*/

[46] Fix | Delete

[47] Fix | Delete

isc_result_t

[48] Fix | Delete

isc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval);

[49] Fix | Delete

/*!<

[50] Fix | Delete

* Set the minimum interval between event executions.

[51] Fix | Delete

* The interval value is copied, so the caller need not preserve it.

[52] Fix | Delete

*

[53] Fix | Delete

* Requires:

[54] Fix | Delete

* '*interval' is a nonzero interval.

[55] Fix | Delete

*/

[56] Fix | Delete

[57] Fix | Delete

void

[58] Fix | Delete

isc_ratelimiter_setpertic(isc_ratelimiter_t *rl, uint32_t perint);

[59] Fix | Delete

/*%<

[60] Fix | Delete

* Set the number of events processed per interval timer tick.

[61] Fix | Delete

* If 'perint' is zero it is treated as 1.

[62] Fix | Delete

*/

[63] Fix | Delete

[64] Fix | Delete

void

[65] Fix | Delete

isc_ratelimiter_setpushpop(isc_ratelimiter_t *rl, bool pushpop);

[66] Fix | Delete

/*%<

[67] Fix | Delete

* Set / clear the ratelimiter to from push pop mode rather

[68] Fix | Delete

* first in - first out mode (default).

[69] Fix | Delete

*/

[70] Fix | Delete

[71] Fix | Delete

isc_result_t

[72] Fix | Delete

isc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task,

[73] Fix | Delete

isc_event_t **eventp);

[74] Fix | Delete

/*%<

[75] Fix | Delete

* Queue an event for rate-limited execution.

[76] Fix | Delete

*

[77] Fix | Delete

* This is similar

[78] Fix | Delete

* to doing an isc_task_send() to the 'task', except that the

[79] Fix | Delete

* execution may be delayed to achieve the desired rate of

[80] Fix | Delete

* execution.

[81] Fix | Delete

*

[82] Fix | Delete

* '(*eventp)->ev_sender' is used to hold the task. The caller

[83] Fix | Delete

* must ensure that the task exists until the event is delivered.

[84] Fix | Delete

*

[85] Fix | Delete

* Requires:

[86] Fix | Delete

*\li An interval has been set by calling

[87] Fix | Delete

* isc_ratelimiter_setinterval().

[88] Fix | Delete

*

[89] Fix | Delete

*\li 'task' to be non NULL.

[90] Fix | Delete

*\li '(*eventp)->ev_sender' to be NULL.

[91] Fix | Delete

*/

[92] Fix | Delete

[93] Fix | Delete

isc_result_t

[94] Fix | Delete

isc_ratelimiter_dequeue(isc_ratelimiter_t *rl, isc_event_t *event);

[95] Fix | Delete

/*

[96] Fix | Delete

* Dequeue a event off the ratelimiter queue.

[97] Fix | Delete

*

[98] Fix | Delete

* Returns:

[99] Fix | Delete

* \li ISC_R_NOTFOUND if the event is no longer linked to the rate limiter.

[100] Fix | Delete

* \li ISC_R_SUCCESS

[101] Fix | Delete

*/

[102] Fix | Delete

[103] Fix | Delete

void

[104] Fix | Delete

isc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter);

[105] Fix | Delete

/*%<

[106] Fix | Delete

* Shut down a rate limiter.

[107] Fix | Delete

*

[108] Fix | Delete

* Ensures:

[109] Fix | Delete

*\li All events that have not yet been

[110] Fix | Delete

* dispatched to the task are dispatched immediately with

[111] Fix | Delete

* the #ISC_EVENTATTR_CANCELED bit set in ev_attributes.

[112] Fix | Delete

*

[113] Fix | Delete

*\li Further attempts to enqueue events will fail with

[114] Fix | Delete

* #ISC_R_SHUTTINGDOWN.

[115] Fix | Delete

*

[116] Fix | Delete

*\li The rate limiter is no longer attached to its task.

[117] Fix | Delete

*/

[118] Fix | Delete

[119] Fix | Delete

void

[120] Fix | Delete

isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target);

[121] Fix | Delete

/*%<

[122] Fix | Delete

* Attach to a rate limiter.

[123] Fix | Delete

*/

[124] Fix | Delete

[125] Fix | Delete

void

[126] Fix | Delete

isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp);

[127] Fix | Delete

/*%<

[128] Fix | Delete

* Detach from a rate limiter.

[129] Fix | Delete

*/

[130] Fix | Delete

[131] Fix | Delete

isc_result_t

[132] Fix | Delete

isc_ratelimiter_stall(isc_ratelimiter_t *rl);

[133] Fix | Delete

/*%<

[134] Fix | Delete

* Stall event processing.

[135] Fix | Delete

*/

[136] Fix | Delete

[137] Fix | Delete

isc_result_t

[138] Fix | Delete

isc_ratelimiter_release(isc_ratelimiter_t *rl);

[139] Fix | Delete

/*%<

[140] Fix | Delete

* Release a stalled rate limiter.

[141] Fix | Delete

*/

[142] Fix | Delete

[143] Fix | Delete

ISC_LANG_ENDDECLS

[144] Fix | Delete

[145] Fix | Delete

#endif /* ISC_RATELIMITER_H */

[146] Fix | Delete

[147] Fix | Delete