Enum Grant 

#[non_exhaustive]
pub enum Grant {
    Now,
    Later(Instant),
    Never,
    LargerThanBurst {
        burst_bytes: u64,
        unit_bytes: u64,
    },
}

What charge decided about one unit.

#[non_exhaustive] with no Default: there is no safe default answer. Defaulting to Now would silently unshape a bucket; defaulting to Never would silently stall one.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Now

The unit may go now. The tokens have already been debited.

Later(Instant)

Not now. The bucket holds enough at this instant and not before, so this is the deadline to arm.

The instant is earliest, not exact: another stream sharing the bucket may drain it again before this one wakes, in which case the next charge answers Later again with a new deadline.

Never

Not now, and no refill instant exists, because the rate is Some(0) and the bucket therefore never refills.

The caller must supply its own deadline, which is the unit’s max_hold clamp. Returning a fabricated far-future instant instead was rejected: it would arm a release timer that never fires, and nothing downstream could tell that deadline from a real one.

LargerThanBurst

Not now, and not ever from tokens: the unit is larger than the whole bucket, so no amount of refilling reaches it.

A separate answer from Self::Never, and the separation is the point. Both leave the caller to fall back on the max_hold clamp, so the two are identical in what they do; they are opposite in what they mean. Never is a rate of zero doing exactly what it was asked to. This is a rate that was asked for and cannot be delivered, because the bucket cannot hold one object’s worth of tokens — every unit leaves at the clamp and the configured rate never binds at all. Folded into one variant, the second is invisible: it produces the same clamp, the same tokens_exhausted_episodes and the same HoldClamped report a working rate limit produces.

Reachable only with a non-zero rate — a zero rate is answered first — so a caller reporting this is always reporting a burst that is too small and never a class that was configured to stop.

Fields

burst_bytes: u64

The bucket’s cap, which is BucketConfig::burst_bytes.

unit_bytes: u64

The unit that did not fit, so the report can quote both numbers rather than leaving the reader to find one of them.

Trait Implementations

impl Clone for Grant

fn clone(&self) -> Grant

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Grant

impl Debug for Grant

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

Formats the value using the given formatter.

impl Eq for Grant

impl PartialEq for Grant

fn eq(&self, other: &Grant) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Grant