diff options
Diffstat (limited to 'lib/isc/include/isc/ratelimiter.h')
| -rw-r--r-- | lib/isc/include/isc/ratelimiter.h | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/lib/isc/include/isc/ratelimiter.h b/lib/isc/include/isc/ratelimiter.h new file mode 100644 index 0000000..45ec447 --- /dev/null +++ b/lib/isc/include/isc/ratelimiter.h @@ -0,0 +1,145 @@ +/* + * Copyright (C) Internet Systems Consortium, Inc. ("ISC") + * + * SPDX-License-Identifier: MPL-2.0 + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, you can obtain one at https://mozilla.org/MPL/2.0/. + * + * See the COPYRIGHT file distributed with this work for additional + * information regarding copyright ownership. + */ + +#pragma once + +/***** +***** Module Info +*****/ + +/*! \file isc/ratelimiter.h + * \brief A rate limiter is a mechanism for dispatching events at a limited + * rate. This is intended to be used when sending zone maintenance + * SOA queries, NOTIFY messages, etc. + */ + +/*** + *** Imports. + ***/ + +#include <inttypes.h> +#include <stdbool.h> + +#include <isc/lang.h> +#include <isc/types.h> + +ISC_LANG_BEGINDECLS + +/***** +***** Functions. +*****/ + +isc_result_t +isc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr, + isc_task_t *task, isc_ratelimiter_t **ratelimiterp); +/*%< + * Create a rate limiter. The execution interval is initially undefined. + */ + +isc_result_t +isc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval); +/*!< + * Set the minimum interval between event executions. + * The interval value is copied, so the caller need not preserve it. + * + * Requires: + * '*interval' is a nonzero interval. + */ + +void +isc_ratelimiter_setpertic(isc_ratelimiter_t *rl, uint32_t perint); +/*%< + * Set the number of events processed per interval timer tick. + * If 'perint' is zero it is treated as 1. + */ + +void +isc_ratelimiter_setpushpop(isc_ratelimiter_t *rl, bool pushpop); +/*%< + * Set / clear the ratelimiter to from push pop mode rather + * first in - first out mode (default). + */ + +isc_result_t +isc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task, + isc_event_t **eventp); +/*%< + * Queue an event for rate-limited execution. + * + * This is similar + * to doing an isc_task_send() to the 'task', except that the + * execution may be delayed to achieve the desired rate of + * execution. + * + * '(*eventp)->ev_sender' is used to hold the task. The caller + * must ensure that the task exists until the event is delivered. + * + * Requires: + *\li An interval has been set by calling + * isc_ratelimiter_setinterval(). + * + *\li 'task' to be non NULL. + *\li '(*eventp)->ev_sender' to be NULL. + */ + +isc_result_t +isc_ratelimiter_dequeue(isc_ratelimiter_t *rl, isc_event_t *event); +/* + * Dequeue a event off the ratelimiter queue. + * + * Returns: + * \li ISC_R_NOTFOUND if the event is no longer linked to the rate limiter. + * \li ISC_R_SUCCESS + */ + +void +isc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter); +/*%< + * Shut down a rate limiter. + * + * Ensures: + *\li All events that have not yet been + * dispatched to the task are dispatched immediately with + * the #ISC_EVENTATTR_CANCELED bit set in ev_attributes. + * + *\li Further attempts to enqueue events will fail with + * #ISC_R_SHUTTINGDOWN. + * + *\li The rate limiter is no longer attached to its task. + */ + +void +isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target); +/*%< + * Attach to a rate limiter. + */ + +void +isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp); +/*%< + * Detach from a rate limiter. + */ + +isc_result_t +isc_ratelimiter_stall(isc_ratelimiter_t *rl); +/*%< + * Stall event processing. + */ + +isc_result_t +isc_ratelimiter_release(isc_ratelimiter_t *rl); +/*%< + * Release a stalled rate limiter. + */ + +ISC_LANG_ENDDECLS |