Current File : //usr/include/bind9/isc/ratelimiter.h
/*
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
*
* 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.
*/
#ifndef ISC_RATELIMITER_H
#define ISC_RATELIMITER_H 1
/*****
***** 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
#endif /* ISC_RATELIMITER_H */
Mini Shell