Enum Acquire 

pub(crate) enum Acquire {
    Now,
    Later(Instant),
    Never,
    LargerThanBurst {
        burst_bytes: u64,
        unit_bytes: u64,
    },
    Starved(Gate),
}

What release decided about one queued unit.

The four “not now” answers are four different waits, and collapsing them is how a shaper stalls or misreports: a bucket that will refill names an instant, a bucket that will never refill names nothing at all, a bucket too small to hold one unit names nothing and is a misconfiguration, and a discipline that is holding the class back names an event.

Variants

Now

Write it. The tokens have already been debited.

Later(Instant)

Not yet — the bucket holds enough at this instant and not before.

Earliest, not exact: another stream sharing the bucket may drain it again first, in which case the next Scheduler::acquire answers Later again with a new instant.

Never

Not yet, and no instant exists: the rate is Some(0), so the bucket never refills. The caller supplies its own deadline — the unit’s max_hold clamp — because arming a fabricated far-future instant would arm a timer that never fires and nothing downstream could tell it from a real deadline.

LargerThanBurst

Not yet, and not ever: this class’s burst_bytes is smaller than the unit at the head of its queue, so its configured rate can never pace anything and every unit leaves at the clamp instead.

Handled exactly as Self::Never is — the clamp is the deadline in both cases — and kept apart from it for one reason: this one is a misconfiguration and Never is a configuration. Without the split the two produce the same clamp, the same tokens_exhausted_episodes and the same HoldClamped, so an author who wrote a rate and left the burst too small reads a throughput unrelated to their number with no signal that anything is wrong. The caller pairs this with Scheduler::claim_burst_report and reports it once per class.

Fields

burst_bytes: u64

The class’s bucket cap.

unit_bytes: u64

The unit it could not cover.

Starved(Gate)

Not yet, and the reason is not the bucket: another class sharing it is ahead under the configured Discipline. Wait on this gate; it is released when the blocking demand withdraws.

Charged to starved_behind_other_class and never to tokens_exhausted_episodes — two causes, two counters.

Trait Implementations

impl Clone for Acquire

fn clone(&self) -> Acquire

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Acquire

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

Formats the value using the given formatter.