tor_async_utils/global_rate_limit.rs
1//! Rate limiter objects backed by a shared [`crate::bw_pool::BandwidthPool`] making them
2//! global as in sharable accross multiple thread/tasks.
3//!
4//! Available in this module is:
5//! * A [`writer::GlobalRateLimitedWriter`] that implements [`futures::AsyncWrite`].
6//! * A [`reader::GlobalRateLimitedReader`] that implements [`futures::AsyncRead`].
7//! * A [`conn::GlobalRateLimitedConn`] that implements both [`futures::AsyncRead`] and
8//! [`futures::AsyncWrite`], rate limiting each direction independently.
9//!
10//! Please read carefully each submodule documentation before using. These can be tricky
11//! to operate without a license ;).
12
13mod conn;
14mod reader;
15mod writer;
16
17pub use conn::GlobalRateLimitedConn;
18pub use reader::GlobalRateLimitedReader;
19pub use writer::GlobalRateLimitedWriter;
20
21use std::io::Error;
22use std::num::NonZero;
23use std::task::{Context, Poll, ready};
24
25use crate::bw_pool::{BandwidthAcquirer, Permit};
26
27/// Convert a `usize` to `u64`. Infallible on every platform we support.
28fn to_u64(x: usize) -> u64 {
29 x.try_into().expect("failed usize to u64 conversion")
30}
31
32/// Convert a `u64` to `usize`. Panics if the value exceeds `usize::MAX`.
33fn to_usize(x: u64) -> usize {
34 x.try_into().expect("failed u64 to usize conversion")
35}
36
37/// Rate-limiting state for a single direction.
38///
39/// It has everything needed to rate limit one direction that is a [`BandwidthAcquirer`]
40/// and an optional maximum chunk.
41///
42/// This is used by the [`GlobalRateLimitedReader`] and [`GlobalRateLimitedWriter`] as
43/// they share that same behavior for each direction (read and write).
44#[derive(Debug)]
45struct DirectionState {
46 /// Acquirer used to get a [`Permit`] from the pool for each poll.
47 acquirer: BandwidthAcquirer,
48 /// Cap on how many tokens a single IO can request.
49 ///
50 /// An IO requests at most this many tokens as long as the buffer is bigger.
51 max_chunk: NonZero<usize>,
52}
53
54impl DirectionState {
55 /// Constructor.
56 fn new(acquirer: BandwidthAcquirer, max_chunk: NonZero<usize>) -> Self {
57 Self {
58 acquirer,
59 max_chunk,
60 }
61 }
62
63 /// Acquire a permit for an IO of the given amount of `tokens`.
64 ///
65 /// The request is capped to the state's max chunk. The grant itself is capped
66 /// to the pool capacity so the returned [`Permit`] can hold less than `tokens`.
67 ///
68 /// The [`Permit`] is handed to the caller rather than kept here so that it lives
69 /// exactly as long as the IO attempt it is for. If the underlying IO turns out to be
70 /// [`Poll::Pending`], the caller drops it and the tokens are refunded to the pool
71 /// instead of being parked for as long as the connection is not ready. That matters
72 /// with many connections as we don't want to hold off ready connections on already
73 /// allocated permits for non ready connections.
74 ///
75 /// The cost is that the caller re-acquires on the next poll rather than resuming
76 /// with what it already had. It is by design.
77 fn poll_acquire(&mut self, cx: &mut Context<'_>, tokens: usize) -> Poll<Result<Permit, Error>> {
78 let want = tokens.min(self.max_chunk.get());
79 let permit = ready!(self.acquirer.poll_acquire(cx, to_u64(want))).map_err(Error::other)?;
80 Poll::Ready(Ok(permit))
81 }
82
83 /// Claim `tokens` on `permit` after a successful IO.
84 ///
85 /// `tokens` must not exceed what the permit was granted. Callers get that by capping
86 /// the IO to [`Permit::granted`].
87 ///
88 /// The permit is consumed so whatever is left unclaimed is refunded on drop.
89 fn commit(mut permit: Permit, tokens: usize) {
90 let claimed = permit.claim(to_u64(tokens));
91 debug_assert!(claimed.is_ok(), "IO reported more than the permit granted");
92 if claimed.is_err() {
93 // The inner misbehaved. Claim it all to avoid refunding what was used.
94 permit.claim_all();
95 }
96 }
97}