Struct BucketConfig 

pub struct BucketConfig { /* private fields */ }

The parameters that define a token bucket.

A bucket holds up to capacity tokens (the burst ceiling) and accrues refill_amount tokens every refill_period (the sustained rate). It starts with initial tokens. These four numbers fully describe the bucket’s behaviour; everything else is accounting.

Construct one with BucketConfig::new, which rejects values that cannot describe a working bucket (see BucketError). The Tier-1 constructors Bucket::per_second and Bucket::per_duration build a config for you for the common case.

initial is clamped to capacity: asking a bucket to start with more tokens than it can hold simply starts it full.

Examples

use better_bucket::BucketConfig;
use std::time::Duration;

// 500-token burst ceiling, refilling 100 tokens/second, starting empty.
let config = BucketConfig::new(500, 100, Duration::from_secs(1), 0)?;
assert_eq!(config.capacity(), 500);
assert_eq!(config.initial(), 0);

Implementations

impl BucketConfig

pub fn new( capacity: u32, refill_amount: u32, refill_period: Duration, initial: u32, ) -> Result<Self, BucketError>

Builds a validated configuration.

Parameters

• capacity — the maximum tokens the bucket holds (its burst size). Must be greater than zero.
• refill_amount — tokens added every refill_period. Must be greater than zero.
• refill_period — the period over which refill_amount accrues. Must be non-zero.
• initial — tokens present at construction, clamped to capacity.

Errors

• BucketError::ZeroCapacity if capacity is 0.
• BucketError::ZeroRefillAmount if refill_amount is 0.
• BucketError::ZeroRefillPeriod if refill_period is zero.

Examples

use better_bucket::BucketConfig;
use std::time::Duration;

let config = BucketConfig::new(100, 100, Duration::from_secs(1), 100)?;
assert_eq!(config.capacity(), 100);

initial larger than capacity is clamped rather than rejected:

use better_bucket::BucketConfig;
use std::time::Duration;

let config = BucketConfig::new(100, 100, Duration::from_secs(1), 999)?;
assert_eq!(config.initial(), 100); // clamped to capacity

pub const fn capacity(&self) -> u32

The maximum number of tokens the bucket holds (its burst ceiling).

pub const fn refill_amount(&self) -> u32

The number of tokens added each refill_period.

pub const fn refill_period(&self) -> Duration

The period over which refill_amount accrues.

pub const fn initial(&self) -> u32

The number of tokens the bucket starts with.

Trait Implementations

impl Clone for BucketConfig

fn clone(&self) -> BucketConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BucketConfig

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

Formats the value using the given formatter.

impl PartialEq for BucketConfig

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for BucketConfig

impl Eq for BucketConfig

impl StructuralPartialEq for BucketConfig