Struct CapacityBucket 

pub struct CapacityBucket { /* private fields */ }

A token bucket for a venue that publishes a capacity and a refill rate, and charges each request a number of tokens.

It starts full, never holds more than capacity, and refills refill_per_sec tokens a second. acquire waits until a request’s tokens are there and takes them.

Capacity is the published burst

This is the opposite of a window quota, and the two must not be made alike. A venue that publishes a bucket’s capacity and rate implements a bucket, so holding the published capacity is a faithful model of it. A window quota publishes a count per window with no capacity term, and a bucket holding that count admits it twice in one window; see WindowQuotaTable.

A cost it can never hold

A request costing more than capacity can never be satisfied, however long it waits. An exact cost is refused at once with Refused, and nothing is sent. An inexact cost (a floor, such as Polymarket’s cancel-all) is charged at capacity and never refused: the server decides.

A bucket made provisional is sized from a guess, before the venue has said what the account’s capacity is. It never refuses: a cost above its capacity waits until confirm or resize, and is then charged or refused.

The hold

acquire waits out the bucket’s Hold before charging, and again after any wait of its own, so a hold set while it waited for tokens is honoured. Every layer of one throttle shares one Hold, and resize keeps it.

A clone shares the tokens and the hold.

Implementations

impl CapacityBucket

pub fn new( layer: LayerId, capacity: u32, refill_per_sec: u32, hold: Hold, ) -> Self

A full bucket for layer holding at most capacity tokens and refilling refill_per_sec a second, waiting out hold.

Panics

When refill_per_sec is zero, since an emptied bucket would never refill.

pub fn provisional( layer: LayerId, capacity: u32, refill_per_sec: u32, hold: Hold, ) -> Self

As new, but sized provisionally: a cost above capacity waits for confirm or resize instead of being refused.

Panics

When refill_per_sec is zero.

pub fn layer(&self) -> LayerId

The layer this bucket charges.

pub fn capacity(&self) -> u32

The most tokens the bucket holds.

pub fn hold(&self) -> &Hold

The hold this bucket waits out.

pub async fn acquire(&self, units: u32, exact: bool) -> Result<(), Refused>

Wait until units tokens are there, then take them.

Waits out the hold first, and again after its own wait. An inexact cost above capacity is charged at capacity.

Errors

Refused at once, before any hold, when exact and units exceed the capacity of a bucket that is not provisional. Nothing is taken.

pub fn resize(&self, capacity: u32, refill_per_sec: u32)

Resize the bucket in place. The tokens it holds are kept, down to the new capacity; the hold is kept; the sizing is confirmed.

Panics

When refill_per_sec is zero.

pub fn confirm(&self)

Confirm a provisional size: a cost above capacity is refused from now on, and those waiting are charged or refused.

Trait Implementations

impl Clone for CapacityBucket

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CapacityBucket

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

Formats the value using the given formatter.