pub struct JsonEncodeAttempt<'a, R, Q>where
Q: ResourceQuantity,{ /* private fields */ }json only.Expand description
I/O accounting and transactional value admission for one JSON encode.
Dropping an attempt rolls back JSON value accounting. Accepted output charges remain committed, including while unwinding from a panic.
§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::json::JsonEncodeLimits;
use qubit_budget::json::JsonEncodeSession;
use qubit_budget::json::JsonMeasurement;
let limits = JsonEncodeLimits::builder().max_nodes(1_usize).build();
let mut session = JsonEncodeSession::from_limits(limits);
let mut attempt = session.begin_value();
attempt.try_admit(JsonMeasurement::Null { depth: 1 }).expect("null should fit");
attempt.commit()?;Implementations§
Source§impl<'a, R, Q> JsonEncodeAttempt<'a, R, Q>where
R: Clone,
Q: ResourceQuantity,
impl<'a, R, Q> JsonEncodeAttempt<'a, R, Q>where
R: Clone,
Q: ResourceQuantity,
Sourcepub fn check_output_bytes(
&self,
amount: usize,
) -> Result<(), MeasuredBudgetError<R, Q>>
pub fn check_output_bytes( &self, amount: usize, ) -> Result<(), MeasuredBudgetError<R, Q>>
Checks whether output bytes fit without charging them.
Returns a quantity-conversion or budget error without changing the configured output budget. An absent output budget is ignored.
§Parameters
amount- Number of output bytes to check without charging.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns MeasuredBudgetError when a native measurement cannot fit Q
or a configured limit rejects it.
Sourcepub fn try_consume_output_bytes(
&mut self,
amount: usize,
) -> Result<(), MeasuredBudgetError<R, Q>>
pub fn try_consume_output_bytes( &mut self, amount: usize, ) -> Result<(), MeasuredBudgetError<R, Q>>
Charges accepted output bytes immediately when the budget is set.
Returns a quantity-conversion or budget error without changing the configured output budget on failure. An absent budget is ignored.
§Parameters
amount- Number of accepted output bytes to charge immediately.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns MeasuredBudgetError when a native measurement cannot fit Q
or a configured limit rejects it.
Sourcepub fn try_admit(
&mut self,
measurement: JsonMeasurement,
) -> Result<(), MeasuredBudgetError<R, Q>>
pub fn try_admit( &mut self, measurement: JsonMeasurement, ) -> Result<(), MeasuredBudgetError<R, Q>>
Stages one JSON measurement for publication by Self::commit.
Returns the transaction’s conversion or value-limit error. A failure leaves this attempt’s working value state and output charges unchanged, and poisons later value admissions and commit. Output failures alone do not poison the value transaction.
§Parameters
measurement- Native JSON measurement to convert or admit.
§Returns
Ok(()) when the operation completes successfully.
§Errors
Returns MeasuredBudgetError when a native measurement cannot fit Q
or a configured limit rejects it.
Sourcepub fn output_budget(&self) -> Option<&ResourceBudget<R, Q>>
pub fn output_budget(&self) -> Option<&ResourceBudget<R, Q>>
Returns the output budget while the attempt exclusively owns it.
§Returns
The caller-owned output budget, still mutably borrowed by this attempt.
None indicates that the corresponding limit or budget dimension is
unconfigured.
Sourcepub fn split_mut(
&mut self,
) -> (Option<&mut ResourceBudget<R, Q>>, &mut JsonValueTransaction<'a, R, Q>)
pub fn split_mut( &mut self, ) -> (Option<&mut ResourceBudget<R, Q>>, &mut JsonValueTransaction<'a, R, Q>)
Splits this attempt into immediate output and staged value accounting.
The output budget, when configured, records accepted bytes immediately. The returned transaction keeps its value changes staged until this attempt is committed. Dropping the attempt rolls back only that value state.
§Returns
A mutable output budget when configured, followed by the staged value transaction. Mutations through the first reference charge output immediately; value changes remain staged until commit.
A None output budget indicates that output-byte accounting is
unconfigured.
Sourcepub fn used_nodes(&self) -> Option<Q>
pub fn used_nodes(&self) -> Option<Q>
Returns staged node usage when the node limit is configured.
§Returns
The node count including successful admissions staged by this attempt.
None indicates that the corresponding limit or budget dimension is
unconfigured.
Sourcepub const fn remaining_nodes(&self) -> Option<Q>
pub const fn remaining_nodes(&self) -> Option<Q>
Returns staged remaining node capacity when the node limit is set.
§Returns
The remaining node capacity after successful staged admissions.
None indicates that the corresponding limit or budget dimension is
unconfigured.
Sourcepub fn used_payload_bytes(&self) -> Option<Q>
pub fn used_payload_bytes(&self) -> Option<Q>
Returns staged payload usage when the payload limit is configured.
§Returns
The payload-byte count including successful admissions staged by this attempt.
None indicates that the corresponding limit or budget dimension is
unconfigured.
Sourcepub const fn remaining_payload_bytes(&self) -> Option<Q>
pub const fn remaining_payload_bytes(&self) -> Option<Q>
Returns staged remaining payload capacity when the payload limit is set.
§Returns
The remaining payload-byte capacity after successful staged admissions.
None indicates that the corresponding limit or budget dimension is
unconfigured.
Sourcepub fn value_transaction_mut(&mut self) -> &mut JsonValueTransaction<'a, R, Q>
pub fn value_transaction_mut(&mut self) -> &mut JsonValueTransaction<'a, R, Q>
Returns the mutable transaction that holds this attempt’s value state.
§Returns
A mutable reference to the transaction whose staged state this attempt will publish on commit.