Struct MultiLimiter 

pub struct MultiLimiter { /* private fields */ }

Available on crate feature std only.

A limiter with several named dimensions, each metered independently.

One outbound call often spends against more than one budget at once. An LLM request, for instance, counts as one request, some number of input tokens, and some number of output tokens — each with its own ceiling. A MultiLimiter holds one limiter per dimension and admits a call only when every dimension can afford its share, applying the per-dimension costs atomically (peek-all-then-commit, like Hybrid).

Costs are supplied per call as (dimension, cost) pairs. A dimension not named in a call is charged nothing; a name with no matching dimension is ignored.

Build one with MultiLimiter::builder.

Examples

use std::time::Duration;
use throttle_net::{MultiLimiter, Throttle};

let minute = Duration::from_secs(60);
let limiter = MultiLimiter::builder()
    .dimension("requests", Throttle::per_duration(60, minute))
    .dimension("input_tokens", Throttle::per_duration(100_000, minute))
    .dimension("output_tokens", Throttle::per_duration(20_000, minute))
    .build();

// A call billed at 1 request, 1500 input tokens, 200 output tokens.
limiter
    .acquire_costs(&[
        ("requests", 1),
        ("input_tokens", 1500),
        ("output_tokens", 200),
    ])
    .await?;

Implementations

impl MultiLimiter

pub fn builder() -> MultiLimiterBuilder

Starts building a multi-dimensional limiter.

pub fn peek_costs(&self, costs: &[(&str, u32)]) -> Decision

Reports whether the call’s per-dimension costs would all be granted now, without taking anything.

Examples

use throttle_net::{MultiLimiter, Throttle};

let limiter = MultiLimiter::builder()
    .dimension("requests", Throttle::per_second(10))
    .dimension("tokens", Throttle::per_second(1000))
    .build();

assert!(limiter.peek_costs(&[("requests", 1), ("tokens", 500)]).is_acquired());

pub fn try_acquire_costs(&self, costs: &[(&str, u32)]) -> bool

Attempts to charge the call’s per-dimension costs without waiting, returning whether every dimension granted.

All-or-nothing across dimensions.

Examples

use throttle_net::{MultiLimiter, Throttle};

let limiter = MultiLimiter::builder()
    .dimension("requests", Throttle::per_second(2))
    .build();

assert!(limiter.try_acquire_costs(&[("requests", 2)]));
assert!(!limiter.try_acquire_costs(&[("requests", 1)]));

pub fn available(&self, dimension: &str) -> Option<u32>

Returns the tokens available in dimension right now, or None if there is no such dimension.

impl MultiLimiter

pub async fn acquire_costs( &self, costs: &[(&str, u32)], ) -> Result<(), ThrottleError>

Available on crate feature runtime only.

Charges the call’s per-dimension costs, waiting until every dimension can afford its share.

This is the headline multi-dimensional operation: it paces the caller until all budgets allow the call, then commits all of them together.

Errors

Returns ThrottleError::CostExceedsCapacity when some dimension’s cost exceeds that dimension’s capacity, naming that dimension’s figures; such a call can never succeed.

Examples

use throttle_net::{MultiLimiter, Throttle};

let limiter = MultiLimiter::builder()
    .dimension("requests", Throttle::per_second(100))
    .dimension("tokens", Throttle::per_second(100_000))
    .build();

limiter.acquire_costs(&[("requests", 1), ("tokens", 1500)]).await?;

Trait Implementations

impl Clone for MultiLimiter

fn clone(&self) -> MultiLimiter

Returns a duplicate of the value.

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

Performs copy-assignment from source.