Struct IterationBudget 

pub struct IterationBudget { /* private fields */ }

Per-surface iteration budget. Counts agent-driven patches per surface; once a surface hits the cap, the handler short-circuits the agent entirely until the surface is reset (typically via delete_surface + create_surface, or an explicit reset).

The budget is in-memory: a single-process daemon keeps its counters for the lifetime of the process. A durable backend using car-state::StateStore::durable is a v2 — the runtime’s transient strategy library doesn’t yet justify persisting iteration counts across restarts.

Implementations

impl IterationBudget

pub fn new() -> Self

pub fn with_max(max: u32) -> Self

pub fn try_consume(&self, surface_id: &str) -> bool

Atomic check-and-increment. Returns true when the surface had budget AND the count has been bumped to claim it; false when the surface is at the cap and the caller must skip the agent invocation. The two steps happen under DashMap’s per-shard lock so concurrent reports for the same surface can’t both pass at count = max - 1.

Pairs with refund for the failed-apply path: the budget is consumed up-front; if the patch apply errors, the handler calls refund to release the slot. That keeps the “budget reflects successful applies” invariant while eliminating the original has_budget + record_apply race.

pub fn refund(&self, surface_id: &str)

Release a budget slot consumed by try_consume when the downstream apply turned out to fail. Saturates at zero so a stray refund without a matching consume can’t drive the counter negative.

pub fn reset(&self, surface_id: &str)

Clear the surface’s counter. Surface recreation triggers this via the caller; the loop is allowed to start over.

pub fn count(&self, surface_id: &str) -> u32

Current iteration count for a surface. Public so the hard-stop log can include it.

pub fn max(&self) -> u32

Trait Implementations

impl Default for IterationBudget

fn default() -> Self

Returns the “default value” for a type.