Struct BudgetHandle 

pub struct BudgetHandle { /* private fields */ }

Cheap, cloneable handle for budget checking from the Lua bridge.

Wraps the shared SessionStatus to expose only budget-related queries. Passed to bridge::register_llm() where it gates every alc.llm() and alc.llm_batch() call.

Call site and threading

Both check() and remaining() are called exclusively from Lua closures registered in bridge.rs, which run on the Lua OS thread. They acquire std::sync::Mutex<SessionStatus> for a few microseconds (read-only field comparisons). See SessionStatus doc for full locking design.

TOCTOU safety of Lua-side alc.budget_check()

The prelude’s alc.budget_check() calls remaining() then the caller decides whether to call alc.llm() (which calls check()). Between remaining() release and check() acquire, llm_calls could theoretically change — but within a single session this is structurally impossible: the Lua thread is the only writer path (via observer callbacks), and observer callbacks only fire after the Lua thread yields control through the mpsc channel. Lua is single-threaded and does not yield between budget_check() and alc.llm().

Poison policy

check() propagates poison as Err — this surfaces as a Lua error, which is the correct behavior since a poisoned mutex indicates an unrecoverable state (OOM panic under lock). remaining() returns Null on poison — it is observational and non-fatal.

Implementations

impl BudgetHandle

pub fn check(&self) -> Result<(), String>

Check if the session is within budget. Returns Err with a message if exceeded.

Propagates mutex poison as Err (see BudgetHandle doc for rationale).

pub fn remaining(&self) -> Value

Remaining budget as JSON: { llm_calls: N|null, elapsed_ms: N|null }. Returns serde_json::Value::Null if no budget is set.

Returns Null on mutex poison (observational, non-fatal).

Trait Implementations

impl Clone for BudgetHandle

fn clone(&self) -> BudgetHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.