pub struct ResourceBudget<R, Q = u64>where
Q: ResourceQuantity,{ /* private fields */ }Expand description
A finite, non-releasable resource budget.
The budget stores remaining capacity and only subtracts after a request has
been checked. Therefore used() is computed as limit - remaining and no
cumulative addition can overflow.
Callers represent an unconfigured dimension with
Option<ResourceBudget<R>> = None rather than constructing an unlimited
object.
§Type Parameters
R- Caller-defined resource value retained for diagnostics.Q- Exact unsigned quantity used for the limit and accounting.
A budget is intentionally not cloneable because cloning would create a second independently consumable copy of the same finite allowance.
§Examples
use qubit_budget::ResourceBudget;
let mut budget = ResourceBudget::new("response bytes", 8_u64);
budget.try_consume(3).expect("three bytes should fit");
assert_eq!(budget.used(), 3);
assert_eq!(budget.remaining(), 5);use qubit_budget::ResourceBudget;
let budget = ResourceBudget::new("bytes", 8_u64);
let _copy = budget.clone();Implementations§
Source§impl<R, Q> ResourceBudget<R, Q>
impl<R, Q> ResourceBudget<R, Q>
Sourcepub fn try_write_string<E, F>(
&mut self,
render: F,
) -> Result<String, BudgetedStringError<R, E, Q>>
pub fn try_write_string<E, F>( &mut self, render: F, ) -> Result<String, BudgetedStringError<R, E, Q>>
Renders and transactionally commits a UTF-8 string under this budget.
§Type Parameters
E- Error type returned by the caller-provided renderer.F- Closure used to render the output string.
§Parameters
render- Caller-provided renderer writing into the transactional adapter.
§Returns
Ok(rendered) after the complete UTF-8 output is charged and committed.
§Errors
Returns BudgetedStringError when rendering, allocation, UTF-8
validation, measurement, or budget accounting fails.
Source§impl<R, Q> ResourceBudget<R, Q>where
Q: ResourceQuantity,
impl<R, Q> ResourceBudget<R, Q>where
Q: ResourceQuantity,
Sourcepub const fn new(resource: R, limit: Q) -> Self
pub const fn new(resource: R, limit: Q) -> Self
Creates a zero-used finite budget.
§Parameters
resource- Domain resource value retained in errors.limit- Finite maximum for this budget.
§Returns
A budget whose remaining capacity equals limit.
§Examples
use qubit_budget::ResourceBudget;
let mut budget = ResourceBudget::new("bytes", 8_u64);
budget.try_consume(3).expect("three bytes should fit");
assert_eq!(budget.used(), 3);
assert_eq!(budget.remaining(), 5);Sourcepub fn from_limit(limit: ResourceLimit<R, Q>) -> Self
pub fn from_limit(limit: ResourceLimit<R, Q>) -> Self
Sourcepub fn check_available(
&self,
amount: Q,
) -> Result<(), InsufficientBudgetError<R, Q>>where
R: Clone,
pub fn check_available(
&self,
amount: Q,
) -> Result<(), InsufficientBudgetError<R, Q>>where
R: Clone,
Checks whether a complete consumption would fit.
§Parameters
amount- Quantity that would be consumed.
§Returns
Ok(()) when amount <= remaining; otherwise returns
InsufficientBudgetError containing the resource, limit and
pre-failure balance. This method never changes the budget.
§Errors
Returns InsufficientBudgetError when amount exceeds the
remaining capacity.
Sourcepub fn try_consume(
&mut self,
amount: Q,
) -> Result<(), InsufficientBudgetError<R, Q>>where
R: Clone,
pub fn try_consume(
&mut self,
amount: Q,
) -> Result<(), InsufficientBudgetError<R, Q>>where
R: Clone,
Consumes an amount atomically when it fits.
§Parameters
amount- Quantity to consume.
§Returns
Ok(()) after subtracting the amount, or a structured error while
leaving remaining unchanged when the amount does not fit.
§Errors
Returns InsufficientBudgetError when amount exceeds the
remaining capacity. The budget remains unchanged in that case.
Sourcepub fn check_available_usize(
&self,
amount: usize,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
pub fn check_available_usize(
&self,
amount: usize,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
Checks a machine-sized consumption request without truncating it.
§Parameters
amount- Native quantity to convert and check.
§Returns
Ok(()) when the converted request fits the remaining capacity.
§Errors
Returns MeasuredBudgetError::Quantity when amount cannot be
represented by Q, or MeasuredBudgetError::Budget when it exceeds
the remaining capacity. The budget is unchanged on either failure.
Sourcepub fn check_available_u64(
&self,
amount: u64,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
pub fn check_available_u64(
&self,
amount: u64,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
Checks a 64-bit consumption request without truncating it.
§Parameters
amount- 64-bit quantity to convert and check.
§Returns
Ok(()) when the converted request fits the remaining capacity.
§Errors
Returns MeasuredBudgetError::Quantity when amount cannot be
represented by Q, or MeasuredBudgetError::Budget when it exceeds
the remaining capacity. The budget is unchanged on either failure.
Sourcepub fn try_consume_usize(
&mut self,
amount: usize,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
pub fn try_consume_usize(
&mut self,
amount: usize,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
Consumes a machine-sized quantity without truncating it.
§Parameters
amount- Native quantity to convert and consume.
§Returns
Ok(()) after the converted quantity is consumed.
§Errors
Returns MeasuredBudgetError::Quantity when amount cannot be
represented by Q, or MeasuredBudgetError::Budget when it exceeds
the remaining capacity. The budget is unchanged on either failure.
Sourcepub fn try_consume_u64(
&mut self,
amount: u64,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
pub fn try_consume_u64(
&mut self,
amount: u64,
) -> Result<(), MeasuredBudgetError<R, Q>>where
R: Clone,
Consumes a 64-bit quantity without truncating it.
§Parameters
amount- 64-bit quantity to convert and consume.
§Returns
Ok(()) after the converted quantity is consumed.
§Errors
Returns MeasuredBudgetError::Quantity when amount cannot be
represented by Q, or MeasuredBudgetError::Budget when it exceeds
the remaining capacity. The budget is unchanged on either failure.
Sourcepub fn try_consume_group(
budgets: &mut [&mut Self],
amount: Q,
) -> Result<(), BudgetGroupError<R, Q>>where
R: Clone,
pub fn try_consume_group(
budgets: &mut [&mut Self],
amount: Q,
) -> Result<(), BudgetGroupError<R, Q>>where
R: Clone,
Atomically consumes the same amount from every budget in a group.
Every member is checked before any member is changed. This is useful when one operation must count against both a local and a shared budget.
§Parameters
budgets- Ordered group of budgets that must all accept the charge.amount- Quantity to consume from each budget.
§Returns
Ok(()) after every budget is charged, or a BudgetGroupError
identifying the first rejecting member. Failure leaves every budget
unchanged.
§Errors
Returns BudgetGroupError when any member has insufficient remaining
capacity.
Sourcepub fn consume_available(&mut self, requested: Q) -> Q
pub fn consume_available(&mut self, requested: Q) -> Q
Sourcepub const fn resource_limit(&self) -> &ResourceLimit<R, Q>
pub const fn resource_limit(&self) -> &ResourceLimit<R, Q>
Returns the immutable resource limit that configures this budget.
§Returns
Returns the immutable resource limit that configures this budget.