Struct BandwidthAcquirer 

pub struct BandwidthAcquirer {
    waiter: Arc<RefillWaiter>,
    in_flight: bool,
    pool: BandwidthPool,
}

A reusable bandwidth acquirer that is designed for an async context (poll).

The main entry point is Self::poll_acquire used within the context of a task which, if rate limited, the task gets woken up when the bandwidth usage is granted.

Fields

waiter: Arc<RefillWaiter>

The shared waiter. Reused for every acquire.

in_flight: bool

Whether this acquirer currently has a request enqueued with the refiller.

Prevent multi poll to avoid queuing a duplicate request with a different waker.

pool: BandwidthPool

The bandwidth pool attached to this acquirer.

Implementations

impl BandwidthAcquirer

fn new(pool: BandwidthPool) -> Self

Create a reusable BandwidthAcquirer for the given pool.

This is the only allocation an acquirer makes. It can only be called from BandwidthPool::new_acquirer.

The number of tokens to acquire is chosen per Self::poll_acquire call.

fn grant_permit(&mut self) -> Permit

Build the Permit.

This sets the in-flight to false and takes the granted tokens out of the waiter, resetting it, as we now hand them to the permit.

pub fn poll_acquire( &mut self, cx: &mut Context<'_>, tokens: u64, ) -> Poll<Result<Permit, BwPoolError>>

Poll to take tokens tokens from the pool, async waiting if the pool is dry.

The number of tokens is per call so the same acquirer can request a different amount each time.

If the request is in flight, the tokens argument is ignored and the originally requested amount is used. Only when a Permit is emitted that a new tokens value can be used.

A request above the pool capacity is clamped to it rather than refused. The emitted Permit then holds less than what was asked and so the caller must use Permit::granted rather than assume it got tokens.

Returns a BwPoolError::PoolClosed error if the BandwidthRefiller has been dropped.

fn enqueue_request( &mut self, cx: &mut Context<'_>, tokens: u64, ) -> Result<(), BwPoolError>

Enqueue a request for tokens tokens that is NOT in flight.

The amount is sent as it was asked. Clamping it to the pool capacity is the refiller’s job as it is the one holding the tokens by the time this is served. The clamping is localized to the refiller for correctness.

Return a BwPoolError::PoolClosed error if the refiller is gone.

Trait Implementations

impl Debug for BandwidthAcquirer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.