Struct TestClock 

pub struct TestClock { /* private fields */ }

Deterministic clock for tests. advance(ns) moves the clock forward; now_ns() reads the current value.

Implementations

impl TestClock

pub fn new() -> Self

Examples found in repository

examples/sample_app.rs (line 218)

fn weighted_message_budget() {
    use std::sync::Arc;

    use subms_rate_limiter::{TestClock, TokenBucket};

    println!("\n== token-bucket: weighted budget that banks idle credit ==");
    let clock = Arc::new(TestClock::new());
    // 10 units of budget, refilling 5 units/sec.
    let budget = TokenBucket::with_clock(10, 5.0, Box::new(SharedClock(clock.clone())));

    assert!(budget.try_acquire(1), "new order costs 1 unit");
    assert!(budget.try_acquire(5), "bulk cancel-replace costs 5 units");
    println!("  after 1 + 5 units: {} left", budget.available());
    assert_eq!(budget.available(), 4);

    // All-or-nothing: a batch of 5 against 4 remaining spends nothing.
    assert!(
        !budget.try_acquire(5),
        "insufficient budget rejects the batch"
    );
    assert_eq!(budget.available(), 4, "a rejected batch spends nothing");

    clock.advance_ms(1_000); // +5 units, capped at 10
    println!("  after 1s idle: {} left", budget.available());
    assert!(budget.try_acquire(5), "banked credit admits the batch");
}

/// `hierarchical` feature: a desk runs two strategy sessions, each rated for
/// its own flow, but the desk's single venue uplink caps the aggregate below
/// the sum - so one hot strategy cannot starve the other.
#[cfg(feature = "hierarchical")]
fn desk_gateway_cap() {
    use std::sync::Arc;

    use subms_rate_limiter::{HierarchicalLimiter, TestClock};

    println!("\n== hierarchical: desk uplink caps two strategies ==");
    let clock = Arc::new(TestClock::new());
    let c = clock.clone();
    // Uplink admits 5 total; each of the two strategies could do 10 alone.
    let desk =
        HierarchicalLimiter::with_clock_fn(5, 0.0, 2, 10, 0.0, || Box::new(SharedClock(c.clone())));

    let mut sent = 0usize;
    for round in 0..10 {
        if desk.try_acquire(round % 2, 1) {
            sent += 1;
        }
    }
    println!("  strategies offered 10 orders; uplink admitted {sent}");
    assert_eq!(sent, 5, "the parent caps the desk aggregate at 5");
}

/// `distributed-backend` feature: an account's venue quota must hold across a
/// fleet of stateless routers. Both consult the same fixed-window counter (the
/// Redis INCR + EXPIRE shape), so the account cannot beat the cap by spraying
/// orders across routers.
#[cfg(feature = "distributed-backend")]
fn per_account_quota() {
    use std::sync::Arc;

    use subms_rate_limiter::{DistributedLimiter, InMemoryBackend, TestClock};

    println!("\n== distributed-backend: one account quota, two routers ==");
    let clock = Arc::new(TestClock::new());
    let shared = Arc::new(InMemoryBackend::new());
    let window_ns = 1_000_000_000u64; // 1s window, 5 orders per account

    let router_a = DistributedLimiter::with_clock(
        Box::new(SharedBackend(shared.clone())),
        5,
        window_ns,
        Box::new(SharedClock(clock.clone())),
    );
    let router_b = DistributedLimiter::with_clock(
        Box::new(SharedBackend(shared.clone())),
        5,
        window_ns,
        Box::new(SharedClock(clock.clone())),
    );

    let account = "acct-42";
    let mut admitted = 0usize;
    for round in 0..8 {
        let router = if round % 2 == 0 { &router_a } else { &router_b };
        if router.try_acquire(account) {
            admitted += 1;
        }
    }
    println!("  8 orders sprayed across 2 routers: {admitted} admitted (quota 5)");
    assert_eq!(admitted, 5, "the shared quota holds across both routers");
}

/// `metrics` feature: cap outbound requests to a market-data vendor and let
/// the limiter be its own metric source - grant / reject counts, refill
/// events, live headroom - with no separate observability layer.
#[cfg(feature = "metrics")]
fn metered_feed_throttle() {
    use std::sync::Arc;

    use subms_rate_limiter::{MeteredTokenBucket, TestClock};

    println!("\n== metrics: self-observing market-data throttle ==");
    let clock = Arc::new(TestClock::new());
    // 5 requests per burst, refilling 100/sec.
    let feed = MeteredTokenBucket::with_clock(5, 100.0, Box::new(SharedClock(clock.clone())));

    for _ in 0..8 {
        feed.try_acquire(1);
    }
    let s = feed.snapshot();
    println!(
        "  granted {}, rejected {}, headroom {}",
        s.granted, s.rejected, s.available
    );
    assert_eq!(s.granted, 5);
    assert_eq!(s.rejected, 3);

    clock.advance_ms(100); // 100/sec -> +10, capped at 5
    assert!(feed.try_acquire(1), "the refilled feed admits again");
    let s2 = feed.snapshot();
    println!(
        "  after refill: granted {}, refills {}",
        s2.granted, s2.refills
    );
    assert_eq!(s2.granted, 6);
    assert!(s2.refills >= 1, "a refill step was observed");
}

pub fn with_start(start_ns: u64) -> Self

pub fn advance(&self, ns: u64)

pub fn advance_ms(&self, ms: u64)

Examples found in repository

examples/sample_app.rs (line 234)

fn weighted_message_budget() {
    use std::sync::Arc;

    use subms_rate_limiter::{TestClock, TokenBucket};

    println!("\n== token-bucket: weighted budget that banks idle credit ==");
    let clock = Arc::new(TestClock::new());
    // 10 units of budget, refilling 5 units/sec.
    let budget = TokenBucket::with_clock(10, 5.0, Box::new(SharedClock(clock.clone())));

    assert!(budget.try_acquire(1), "new order costs 1 unit");
    assert!(budget.try_acquire(5), "bulk cancel-replace costs 5 units");
    println!("  after 1 + 5 units: {} left", budget.available());
    assert_eq!(budget.available(), 4);

    // All-or-nothing: a batch of 5 against 4 remaining spends nothing.
    assert!(
        !budget.try_acquire(5),
        "insufficient budget rejects the batch"
    );
    assert_eq!(budget.available(), 4, "a rejected batch spends nothing");

    clock.advance_ms(1_000); // +5 units, capped at 10
    println!("  after 1s idle: {} left", budget.available());
    assert!(budget.try_acquire(5), "banked credit admits the batch");
}

/// `hierarchical` feature: a desk runs two strategy sessions, each rated for
/// its own flow, but the desk's single venue uplink caps the aggregate below
/// the sum - so one hot strategy cannot starve the other.
#[cfg(feature = "hierarchical")]
fn desk_gateway_cap() {
    use std::sync::Arc;

    use subms_rate_limiter::{HierarchicalLimiter, TestClock};

    println!("\n== hierarchical: desk uplink caps two strategies ==");
    let clock = Arc::new(TestClock::new());
    let c = clock.clone();
    // Uplink admits 5 total; each of the two strategies could do 10 alone.
    let desk =
        HierarchicalLimiter::with_clock_fn(5, 0.0, 2, 10, 0.0, || Box::new(SharedClock(c.clone())));

    let mut sent = 0usize;
    for round in 0..10 {
        if desk.try_acquire(round % 2, 1) {
            sent += 1;
        }
    }
    println!("  strategies offered 10 orders; uplink admitted {sent}");
    assert_eq!(sent, 5, "the parent caps the desk aggregate at 5");
}

/// `distributed-backend` feature: an account's venue quota must hold across a
/// fleet of stateless routers. Both consult the same fixed-window counter (the
/// Redis INCR + EXPIRE shape), so the account cannot beat the cap by spraying
/// orders across routers.
#[cfg(feature = "distributed-backend")]
fn per_account_quota() {
    use std::sync::Arc;

    use subms_rate_limiter::{DistributedLimiter, InMemoryBackend, TestClock};

    println!("\n== distributed-backend: one account quota, two routers ==");
    let clock = Arc::new(TestClock::new());
    let shared = Arc::new(InMemoryBackend::new());
    let window_ns = 1_000_000_000u64; // 1s window, 5 orders per account

    let router_a = DistributedLimiter::with_clock(
        Box::new(SharedBackend(shared.clone())),
        5,
        window_ns,
        Box::new(SharedClock(clock.clone())),
    );
    let router_b = DistributedLimiter::with_clock(
        Box::new(SharedBackend(shared.clone())),
        5,
        window_ns,
        Box::new(SharedClock(clock.clone())),
    );

    let account = "acct-42";
    let mut admitted = 0usize;
    for round in 0..8 {
        let router = if round % 2 == 0 { &router_a } else { &router_b };
        if router.try_acquire(account) {
            admitted += 1;
        }
    }
    println!("  8 orders sprayed across 2 routers: {admitted} admitted (quota 5)");
    assert_eq!(admitted, 5, "the shared quota holds across both routers");
}

/// `metrics` feature: cap outbound requests to a market-data vendor and let
/// the limiter be its own metric source - grant / reject counts, refill
/// events, live headroom - with no separate observability layer.
#[cfg(feature = "metrics")]
fn metered_feed_throttle() {
    use std::sync::Arc;

    use subms_rate_limiter::{MeteredTokenBucket, TestClock};

    println!("\n== metrics: self-observing market-data throttle ==");
    let clock = Arc::new(TestClock::new());
    // 5 requests per burst, refilling 100/sec.
    let feed = MeteredTokenBucket::with_clock(5, 100.0, Box::new(SharedClock(clock.clone())));

    for _ in 0..8 {
        feed.try_acquire(1);
    }
    let s = feed.snapshot();
    println!(
        "  granted {}, rejected {}, headroom {}",
        s.granted, s.rejected, s.available
    );
    assert_eq!(s.granted, 5);
    assert_eq!(s.rejected, 3);

    clock.advance_ms(100); // 100/sec -> +10, capped at 5
    assert!(feed.try_acquire(1), "the refilled feed admits again");
    let s2 = feed.snapshot();
    println!(
        "  after refill: granted {}, refills {}",
        s2.granted, s2.refills
    );
    assert_eq!(s2.granted, 6);
    assert!(s2.refills >= 1, "a refill step was observed");
}

Trait Implementations

impl Clock for TestClock

fn now_ns(&self) -> u64

Nanoseconds since the clock’s origin. Monotonic non-decreasing.

impl Default for TestClock

fn default() -> Self

Returns the “default value” for a type.