https://github.com/fredmorcos/throttle_my_fn
A Rust attribute macro to limit a function's number of runs over a specified period of time
https://github.com/fredmorcos/throttle_my_fn
macro macros rate-limiter rate-limiting rust rust-crate rust-lang throttle
Last synced: 2 months ago
JSON representation
A Rust attribute macro to limit a function's number of runs over a specified period of time
- Host: GitHub
- URL: https://github.com/fredmorcos/throttle_my_fn
- Owner: fredmorcos
- License: mit
- Created: 2021-11-12T09:05:13.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-08-16T12:53:00.000Z (almost 4 years ago)
- Last Synced: 2026-03-15T12:52:44.741Z (3 months ago)
- Topics: macro, macros, rate-limiter, rate-limiting, rust, rust-crate, rust-lang, throttle
- Language: Rust
- Homepage:
- Size: 15.6 KB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `throttle_my_fn`: A Rust attribute macro to throttle the execution of functions
[](https://github.com/fredmorcos/throttle_my_fn/blob/main/LICENSE)
[](https://crates.io/crates/throttle_my_fn)
[](https://docs.rs/throttle_my_fn/0.2.6/throttle_my_fn/)
`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`:
```toml
[dependencies]
throttle_my_fn = "0.2"
parking_lot = "0.11"
```
Or, using `cargo add`:
```sh
$ cargo add throttle_my_fn
$ cargo add parking_lot
```
Include the macro:
```rust
use throttle_my_fn::throttle;
```
Annotate the functions you want to throttle:
```rust
#[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:
```rust
pub(crate) fn run_10_times_per_second(arg: &str) -> Option {
...
}
pub(crate) fn run_once_per_100_milliseconds(arg: &str) -> Option {
...
}
```
The `Option` 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