Struct Budget 

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

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 urgency 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

impl Budget

pub const INFINITE: Budget

A budget with no constraints (infinite resources).

pub const ZERO: Budget

A budget with zero resources (nothing allowed).

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.

pub const fn new() -> Budget

Creates a new budget with default values (priority 128, unlimited quotas).

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());

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

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

The value is a logical instant since the runtime epoch, not a timeout duration. For a per-operation timeout, use with_timeout with the current logical time.

Example

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

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

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

The value is a logical instant since the runtime epoch, not a timeout duration. For a per-operation timeout, use with_timeout with the current logical time.

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)));

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

Sets the absolute logical deadline.

The deadline is an instant, not a duration. For example, Time::from_secs(30) means the runtime/lab clock value 30s, not “30 seconds from now”. For relative per-operation timeouts, use with_timeout.

pub fn with_timeout(self, now: Time, timeout: Duration) -> Budget

Sets the deadline to now + timeout.

Use this for request, RPC, database, and other per-operation timeout budgets. The caller supplies now explicitly so production and lab runtimes use the same deterministic time source.

Example

let now = Time::from_secs(100);
let budget = Budget::new().with_timeout(now, Duration::from_secs(30));

assert_eq!(budget.deadline, Some(Time::from_secs(130)));

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

Sets the poll quota.

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

Sets the cost quota.

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

Sets the priority.

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).

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

Returns true if the deadline has passed.

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

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

Returns None if already at zero.

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 urgency 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

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)));

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

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)));

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);

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);

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)));

Trait Implementations

impl BudgetTimeExt for Budget

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

Get remaining time until deadline.

fn deadline_sleep(&self) -> Option<Sleep>

Create sleep that respects budget deadline.

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

Check if deadline has passed.

impl Clone for Budget

fn clone(&self) -> Budget

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Budget

impl Debug for Budget

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

Formats the value using the given formatter.

impl Default for Budget

fn default() -> Budget

Returns the “default value” for a type.

impl Eq for Budget

impl LocalToDistributed for Budget

type Distributed = BudgetSnapshot

The distributed equivalent type.

fn to_distributed(&self) -> BudgetSnapshot

Converts to the distributed equivalent.

impl PartialEq for Budget

fn eq(&self, other: &Budget) -> 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 StructuralPartialEq for Budget