Struct BucketBuilder 

pub struct BucketBuilder { /* private fields */ }

A fluent builder for a Bucket when the Tier-1 constructors are not enough.

Set the capacity (the burst ceiling), the refill rate, and optionally the initial fill, then call build. Anything left unset keeps its default, and build validates the result through BucketConfig::new, so an unworkable combination is rejected rather than producing a misbehaving bucket.

Capacity and burst are the same thing for a token bucket: the bucket holds at most capacity tokens, so the largest single acquire it can ever grant — the burst — is capacity.

For a custom time source, chain Bucket::with_clock onto the built bucket; the builder itself always produces a SystemClock bucket.

Examples

use better_bucket::Bucket;
use std::time::Duration;

// Burst up to 1000, refill 50/second, start empty.
let bucket = Bucket::builder()
    .capacity(1000)
    .refill(50, Duration::from_secs(1))
    .initial(0)
    .build()?;

assert_eq!(bucket.capacity(), 1000);
assert_eq!(bucket.available(), 0);

Implementations

impl BucketBuilder

pub fn new() -> Self

Starts a builder with every field at its default (which build rejects until at least a capacity and refill rate are set).

pub fn capacity(self, capacity: u32) -> Self

Sets the capacity — the maximum tokens the bucket holds, and therefore the largest burst it can grant at once. Required.

Examples

use better_bucket::Bucket;
use std::time::Duration;

let bucket = Bucket::builder()
    .capacity(200)
    .refill(200, Duration::from_secs(1))
    .build()?;
assert_eq!(bucket.capacity(), 200);

pub fn refill(self, amount: u32, period: Duration) -> Self

Sets the sustained refill rate: amount tokens every period. Required.

Examples

use better_bucket::Bucket;
use std::time::Duration;

// 10 tokens every 250ms.
let bucket = Bucket::builder()
    .capacity(10)
    .refill(10, Duration::from_millis(250))
    .build()?;

pub fn initial(self, initial: u32) -> Self

Sets the initial number of tokens. Defaults to the capacity (the bucket starts full); values above the capacity are clamped to it.

Examples

use better_bucket::Bucket;
use std::time::Duration;

let bucket = Bucket::builder()
    .capacity(100)
    .refill(100, Duration::from_secs(1))
    .initial(0) // start empty instead of full
    .build()?;
assert_eq!(bucket.available(), 0);

pub fn build(self) -> Result<Bucket<SystemClock>, BucketError>

Validates the configuration and builds the bucket.

Errors

Returns a BucketError for the same reasons as BucketConfig::new: zero capacity, zero refill amount, or zero refill period. A freshly created builder fails this way until a capacity and refill rate are set.

Examples

use better_bucket::{Bucket, BucketError};

// Nothing configured yet → rejected.
let err = Bucket::builder().build().unwrap_err();
assert_eq!(err, BucketError::ZeroCapacity);

Trait Implementations

impl Clone for BucketBuilder

fn clone(&self) -> BucketBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BucketBuilder

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

Formats the value using the given formatter.

impl Default for BucketBuilder

fn default() -> BucketBuilder

Returns the “default value” for a type.