pub struct StructureBudget<R = StructureResource, Q = usize>where
Q: ResourceQuantity,{ /* private fields */ }Expand description
Mutable structural accounting for one processing session.
R and Q mirror StructureLimits. Point limits do not accumulate
between calls; node charges consume the session’s finite node budget.
Obtain a StructureBudget from StructureLimits::budget after building
the limits. The budget is intended to be kept for one processing session.
§Type Parameters
R- Caller-defined resource identity retained by limits and errors.Q- Exact unsigned quantity used for measurements and accounting.
§Examples
use qubit_budget::StructureLimits;
let limits = StructureLimits::builder().max_nodes(2).build();
let mut budget = limits.budget();
budget.charge_node().expect("first node should fit");
budget.charge_node().expect("second node should fit");
assert_eq!(budget.used_nodes(), Some(2));
assert!(budget.charge_node().is_err());Implementations§
Source§impl<R, Q> StructureBudget<R, Q>where
R: Clone,
Q: ResourceQuantity,
impl<R, Q> StructureBudget<R, Q>where
R: Clone,
Q: ResourceQuantity,
Sourcepub fn check_depth(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
pub fn check_depth(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
Checks one nesting depth against its configured maximum.
§Parameters
actual- Observed nesting depth to compare with the configured depth limit.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when a configured depth limit
rejects actual.
Sourcepub fn charge_node(&mut self) -> Result<(), BudgetError<R, Q>>
pub fn charge_node(&mut self) -> Result<(), BudgetError<R, Q>>
Charges one processed node to this session’s cumulative node budget.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::Insufficient when the configured node budget
has fewer than one unit remaining.
Sourcepub fn charge_nodes(&mut self, amount: Q) -> Result<(), BudgetError<R, Q>>
pub fn charge_nodes(&mut self, amount: Q) -> Result<(), BudgetError<R, Q>>
Charges several processed nodes atomically.
§Parameters
amount- Number of nodes to charge from the cumulative node budget.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::Insufficient when the configured node budget
has fewer than amount units remaining.
Sourcepub fn check_sequence_items(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
pub fn check_sequence_items(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
Checks one sequence item count against its configured maximum.
§Parameters
actual- Observed number of direct items in the sequence.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when a configured sequence-item
limit rejects actual.
Sourcepub fn check_map_entries(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
pub fn check_map_entries(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
Checks one map entry count against its configured maximum.
§Parameters
actual- Observed number of direct entries in the map.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when a configured map-entry
limit rejects actual.
Sourcepub fn check_key_bytes(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
pub fn check_key_bytes(&self, actual: Q) -> Result<(), BudgetError<R, Q>>
Checks one structural key byte length against its configured maximum.
§Parameters
actual- Observed UTF-8 byte length of the structural key.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when a configured key-byte limit
rejects actual.
Sourcepub fn enter_node(&mut self, depth: Q) -> Result<(), BudgetError<R, Q>>
pub fn enter_node(&mut self, depth: Q) -> Result<(), BudgetError<R, Q>>
Checks a value depth and charges one node as one atomic traversal step.
§Parameters
depth- Root-inclusive nesting depth to validate.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when the depth limit rejects
depth, or BudgetError::Insufficient when the node budget has no
remaining unit.
Sourcepub fn enter_sequence(
&mut self,
depth: Q,
items: Q,
) -> Result<(), BudgetError<R, Q>>
pub fn enter_sequence( &mut self, depth: Q, items: Q, ) -> Result<(), BudgetError<R, Q>>
Checks a sequence size and charges one node as one atomic traversal step.
§Parameters
depth- Root-inclusive nesting depth to validate.items- Number of direct sequence or array items.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when the depth or sequence-item
limit rejects its measurement, or BudgetError::Insufficient when
the node budget has no remaining unit.
Sourcepub fn enter_map(
&mut self,
depth: Q,
entries: Q,
) -> Result<(), BudgetError<R, Q>>
pub fn enter_map( &mut self, depth: Q, entries: Q, ) -> Result<(), BudgetError<R, Q>>
Checks a map size and charges one node as one atomic traversal step.
§Parameters
depth- Root-inclusive nesting depth to validate.entries- Number of direct map or object entries.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns BudgetError::LimitExceeded when the depth or map-entry
limit rejects its measurement, or BudgetError::Insufficient when
the node budget has no remaining unit.
Sourcepub const fn limits(&self) -> &StructureLimits<R, Q>
pub const fn limits(&self) -> &StructureLimits<R, Q>
Returns the immutable limits copied into this session.
§Returns
Returns the immutable limits copied into this session.
Sourcepub const fn has_nodes_limit(&self) -> bool
pub const fn has_nodes_limit(&self) -> bool
Returns whether this session has a finite node limit.
§Returns
true when the source limits configured a cumulative node maximum.
Sourcepub const fn remaining_nodes(&self) -> Option<Q>
pub const fn remaining_nodes(&self) -> Option<Q>
Returns the node capacity remaining in this session.
§Returns
The remaining capacity when a node limit is configured, or None for
an unconfigured node dimension.
Sourcepub fn used_nodes(&self) -> Option<Q>
pub fn used_nodes(&self) -> Option<Q>
Returns the number of nodes consumed by this session when configured.
§Returns
Some(used) contains the cumulative node usage when a node limit is
configured. None indicates an unconfigured node dimension.