Skip to main content

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}