Struct BandwidthPool 

pub struct BandwidthPool {
    bucket: Arc<AtomicTokenBucket>,
    requests: UnboundedSender<(u64, Arc<RefillWaiter>)>,
}

A shareable bandwidth pool.

Use Self::share to give it to each task requiring bandwidth limitation.

Clone is deliberately not implemented so that handing this around can not be mistaken for creating a second pool with its own bandwidth. There is exactly one pool per Self::new call.

Each task needs to hold a BandwidthAcquirer in order to request bandwidth permits from this pool.

Fields

bucket: Arc<AtomicTokenBucket>

The shared token bucket the fast path claims from.

requests: UnboundedSender<(u64, Arc<RefillWaiter>)>

Ingress for acquirers that failed the fast path.

Sending a BwRequest here both enqueues it and wakes the BandwidthRefiller

Unbounded because we never want an acquirer’s enqueue to block. the number of in-flight requests is bounded by the number of acquirers.

Implementations

impl BandwidthPool

pub fn new(capacity: u64) -> (BandwidthPool, BandwidthRefiller)

Create a new pool that can hold up to capacity tokens, and its associated refiller BandwidthRefiller that needs to be run in its own task.

The pool starts full and capacity tokens are immediately available to the fast path.

pub fn share(&self) -> BandwidthPool

Return another BandwidthPool that is the same as this one.

The tokens are not duplicated, this is so you can share the pool with other tasks/objects.

pub fn new_acquirer(&self) -> BandwidthAcquirer

Return a new BandwidthAcquirer associated to this pool.

The number of tokens to acquire is chosen per BandwidthAcquirer::poll_acquire call, so a single acquirer can be reused for requests of different sizes.

It is through an acquirer that one can get permission to use bandwidth. See BandwidthAcquirer::poll_acquire.

pub fn capacity(&self) -> u64

The maximum number of tokens this pool can hold (its burst).

fn is_closed(&self) -> bool

Return true iff the refiller is gone, meaning this pool is closed.

fn try_acquire(&self, tokens: u64) -> Option<Permit>

Try to take tokens from the pool without waiting.

A request above the pool capacity is clamped to it by the bucket it self so the permit can hold less than what was asked. The caller learns what it got with Permit::granted.

Returns Some(permit) if there were tokens available right now, or None if the bucket is empty.

This never blocks and never enqueues. It is the fast path that the other acquisition methods use first.

Trait Implementations

impl Debug for BandwidthPool

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

Formats the value using the given formatter.