/throttle_my_fn

A Rust attribute macro to limit a function's number of runs over a specified period of time

Primary LanguageRustMIT LicenseMIT

throttle_my_fn: A Rust attribute macro to throttle the execution of functions

License Crates.io docs.rs

throttle_my_fn is a Rust attribute macro to limit a function's number of runs over a specified period of time, even when called from multiple threads.

The primary use-case for this attribute macro is rate-limiting, e.g. to avoid hammering an online service or to avoid serving too many requests over a period of time.

The macro works by rewriting the function and prefixing it with the necessary book-keeping for throttling (see Usage below). The resulting function is thread-safe.

Usage

Add the necessary dependencies to your Cargo.toml:

[dependencies]
throttle_my_fn = "0.2"
parking_lot = "0.11"

Or, using cargo add:

$ cargo add throttle_my_fn
$ cargo add parking_lot

Include the macro:

use throttle_my_fn::throttle;

Annotate the functions you want to throttle:

#[throttle(10, Duration::from_secs(1))]
pub(crate) fn run_10_times_per_second(arg: &str) -> String {
  ...
}

#[throttle(1, Duration::from_millis(100))]
pub(crate) fn run_once_per_100_milliseconds(arg: &str) -> String {
  ...
}

Note that the function signatures are modified to wrap the return type in an Option, like so:

pub(crate) fn run_10_times_per_second(arg: &str) -> Option<String> {
  ...
}

pub(crate) fn run_once_per_100_milliseconds(arg: &str) -> Option<String> {
  ...
}

The Option<T> returned signifies whether the function executed or not.

Changelog

  • 0.2.6

    • Fix compilation error with functions that have 2+ arguments.

  • 0.2.5

    • README fixes.

  • 0.2.4

    • Ignore example doctests.
    • Update documentation about also adding parking_lot as a dependency.

  • 0.2.3

    • Add this Changelog section to the README.

  • 0.2.2

    • Documentation updates regarding thread-safety.

  • 0.2.1

    • Documentation update about possible use cases for this crate.
    • Thanks go to @not-matthias from the Rust Linz Discord server for feedback.

  • 0.2.0

    • Replace the use of MaybeUninit and AtomicBool with parking_lot::Mutex and parking_lot::const_mutex.
    • Thanks go to @mejrs and @veber-alex from the Rust Discord server for feedback.

  • 0.1.0

    • Initial release