Struct Budget

Source

pub struct Budget {
    pub deadline: Option<Time>,
    pub poll_quota: u32,
    pub cost_quota: Option<u64>,
    pub priority: u8,
}

Expand description

A budget constraining resource usage for a task or region.

Budgets form a product semiring for combination:

Deadlines/quotas use min (tighter wins)
Priority uses max (higher wins)

Fields§

§deadline: Option<Time>

Absolute deadline by which work must complete.

§poll_quota: u32

Maximum number of poll operations.

§cost_quota: Option<u64>

Abstract cost quota (for advanced scheduling).

§priority: u8

Scheduling priority (0 = lowest, 255 = highest).

Implementations§

Source §

impl Budget

Source

pub const INFINITE: Budget

A budget with no constraints (infinite resources).

Source

pub const ZERO: Budget

A budget with zero resources (nothing allowed).

Source

pub const MINIMAL: Budget

A minimal budget for cleanup operations.

This provides a small poll quota (100 polls) for cleanup and finalizer code to run, but no deadline or cost constraints. Used when requesting cancellation to allow tasks a bounded cleanup phase.

Source

pub const fn new() -> Budget

Creates a new budget with default values (unlimited).

Source

pub const fn unlimited() -> Budget

Creates an unlimited budget (alias for INFINITE).

This is the identity element for the meet operation.

§Example

let budget = Budget::unlimited();
assert!(!budget.is_exhausted());

Source

pub const fn with_deadline_secs(secs: u64) -> Budget

Creates a budget with only a deadline constraint (in seconds).

This is a convenience constructor for HTTP timeout scenarios.

§Example

let budget = Budget::with_deadline_secs(30);
assert_eq!(budget.deadline, Some(Time::from_secs(30)));

Source

pub const fn with_deadline_ns(nanos: u64) -> Budget

Creates a budget with only a deadline constraint (in nanoseconds).

§Example

let budget = Budget::with_deadline_ns(30_000_000_000); // 30 seconds
assert_eq!(budget.deadline, Some(Time::from_nanos(30_000_000_000)));

Source

pub const fn with_deadline(self, deadline: Time) -> Budget

Sets the deadline.

Source

pub const fn with_poll_quota(self, quota: u32) -> Budget

Sets the poll quota.

Source

pub const fn with_cost_quota(self, quota: u64) -> Budget

Sets the cost quota.

Source

pub const fn with_priority(self, priority: u8) -> Budget

Sets the priority.

Source

pub const fn is_exhausted(&self) -> bool

Returns true if the budget has been exhausted.

This checks only poll and cost quotas, not deadline (which requires current time).

Source

pub fn is_past_deadline(&self, now: Time) -> bool

Returns true if the deadline has passed.

Source

pub fn consume_poll(&mut self) -> Option<u32>

Decrements the poll quota by one, returning the old value.

Returns None if already at zero.

Source

pub fn combine(self, other: Budget) -> Budget

Combines two budgets using product semiring semantics.

Deadlines: min (earlier wins)
Quotas: min (tighter wins)
Priority: max (higher wins)

This is also known as the “meet” operation (∧) in lattice terminology. See also: meet.

§Example

let outer = Budget::new()
    .with_deadline(Time::from_secs(30))
    .with_poll_quota(1000);

let inner = Budget::new()
    .with_deadline(Time::from_secs(10))  // tighter
    .with_poll_quota(5000);              // looser

let combined = outer.combine(inner);
assert_eq!(combined.deadline, Some(Time::from_secs(10))); // min
assert_eq!(combined.poll_quota, 1000);                    // min

Source

pub fn meet(self, other: Budget) -> Budget

Meet operation (∧) - alias for combine.

Computes the tightest constraints from two budgets. This is the fundamental operation for nesting budget scopes.

§Example

let parent = Budget::with_deadline_secs(30);
let child = Budget::with_deadline_secs(10);

// Child deadline is tighter, so it wins
let effective = parent.meet(child);
assert_eq!(effective.deadline, Some(Time::from_secs(10)));

Source

pub fn consume_cost(&mut self, cost: u64) -> bool

Consumes cost quota, returning true if successful.

Returns false (and does not modify quota) if there isn’t enough remaining cost quota. If no cost quota is set, always succeeds.

§Example

let mut budget = Budget::new().with_cost_quota(100);

assert!(budget.consume_cost(30));   // 70 remaining
assert!(budget.consume_cost(70));   // 0 remaining
assert!(!budget.consume_cost(1));   // fails, quota exhausted

Source

pub fn remaining_time(&self, now: Time) -> Option<Duration>

Returns the remaining time until the deadline, if any.

Returns None if there is no deadline or if the deadline has passed.

§Example

let budget = Budget::with_deadline_secs(30);
let now = Time::from_secs(10);

let remaining = budget.remaining_time(now);
assert_eq!(remaining, Some(Duration::from_secs(20)));

Source

pub const fn remaining_polls(&self) -> u32

Returns the remaining poll quota.

Returns the current poll quota value. A value of u32::MAX indicates effectively unlimited polls.

§Example

let budget = Budget::new().with_poll_quota(100);
assert_eq!(budget.remaining_polls(), 100);

Source

pub const fn remaining_cost(&self) -> Option<u64>

Returns the remaining cost quota, if any.

Returns None if no cost quota is set (unlimited).

§Example

let budget = Budget::new().with_cost_quota(1000);
assert_eq!(budget.remaining_cost(), Some(1000));

let unlimited = Budget::unlimited();
assert_eq!(unlimited.remaining_cost(), None);

Source

pub fn to_timeout(&self, now: Time) -> Option<Duration>

Converts the deadline to a timeout duration from the given time.

Returns the same value as remaining_time. This method is provided for API compatibility with timeout-based systems.

§Example

let budget = Budget::with_deadline_secs(30);
let now = Time::from_secs(5);

// 25 seconds remaining
let timeout = budget.to_timeout(now);
assert_eq!(timeout, Some(Duration::from_secs(25)));