pub struct Meter { /* private fields */ }Expand description
One open of an input: what the input holds, against
Limits::max_input_memory, and what this open has done, against
Limits::max_decode_work (module docs). Thread-safe: a lazily read
bundle’s entries charge one meter from any thread. Shared as
Arc<Meter>; every Charge keeps it alive.
Implementations§
Source§impl Meter
impl Meter
Sourcepub const OWN_HEAP: u64
pub const OWN_HEAP: u64
The heap an input’s first meter takes itself, outside every charge,
in glibc chunks (heap_cost): the meter and the memory account, each
in its Arc (plan section 3.15’s constant per input). Each
Self::reopen adds Self::REOPEN_HEAP.
Sourcepub const REOPEN_HEAP: u64
pub const REOPEN_HEAP: u64
The heap one more open’s meter takes, in glibc chunks.
Sourcepub fn allocator_refused(&self, requested: u64) -> AllocError
pub fn allocator_refused(&self, requested: u64) -> AllocError
Records one detected allocator refusal on this meter’s budget and returns its provenance. Call only at detection, never in conversions. Arithmetic/count overflow must use the corresponding limit error.
Sourcepub fn new(
limit: u64,
budget: Arc<dyn MemoryBudget>,
what: Reservation,
) -> Arc<Self> ⓘ
pub fn new( limit: u64, budget: Arc<dyn MemoryBudget>, what: Reservation, ) -> Arc<Self> ⓘ
A meter of limit bytes whose charges are booked with budget as
what, with no bound on decode work.
Sourcepub fn with_decode_work(
limit: u64,
max_decode_work: u64,
budget: Arc<dyn MemoryBudget>,
what: Reservation,
) -> Arc<Self> ⓘ
pub fn with_decode_work( limit: u64, max_decode_work: u64, budget: Arc<dyn MemoryBudget>, what: Reservation, ) -> Arc<Self> ⓘ
A meter of limit bytes that also counts decode work up to
max_decode_work bytes (Self::count_decode).
Sourcepub fn for_input(
limits: &Limits,
budget: Arc<dyn MemoryBudget>,
what: Reservation,
) -> Arc<Self> ⓘ
pub fn for_input( limits: &Limits, budget: Arc<dyn MemoryBudget>, what: Reservation, ) -> Arc<Self> ⓘ
The meter of one input loaded with limits and budget: its memory
bound is Limits::max_input_memory and its decode-work bound
Limits::max_decode_work.
Sourcepub fn reopen(&self) -> Arc<Self> ⓘ
pub fn reopen(&self) -> Arc<Self> ⓘ
A meter for opening the same input again: it charges the same memory
account, so everything every open holds counts against one
Limits::max_input_memory, and its work starts from zero with the
same bound. The Environment opens an evicted dependency again on it
(plan section 3.13). The old meter keeps its own count, so a handle
of the old open that something still holds (a nested bundle a
resource read kept) goes on counting against the old allowance, which
nothing resets, and every open’s work stays bounded.
Sourcepub fn work_scope(&self, limit: u64) -> Arc<Self> ⓘ
pub fn work_scope(&self, limit: u64) -> Arc<Self> ⓘ
Separate work allowance on the same memory account, for caller-side export.
Sourcepub fn attempted_work(&self) -> u64
pub fn attempted_work(&self) -> u64
Work attempted by this scope, including its largest refused increment.
Sourcepub fn same_input(&self, other: &Self) -> bool
pub fn same_input(&self, other: &Self) -> bool
Whether other charges the same input’s memory (one of them is a
Self::reopen of the other, or they are the same meter).
Sourcepub fn count_decode(&self, bytes: u64) -> Result<(), ChargeError>
pub fn count_decode(&self, bytes: u64) -> Result<(), ChargeError>
Counts bytes of this open’s work, refused when it would pass the
bound (LimitKind::DecodeWork): one atomic check-and-add, so work
counted at once from several threads never passes the bound. Work is
never returned while the open lives, whatever its charges do. A
refused decode counts nothing, so a smaller one may still fit; once
work has passed the bound (add_work, unchecked), every later decode on
this meter is refused. A
crate::budget::DecodeBuf counts every write of a block’s segment:
one that needs a growth after the meter and the budget granted its
memory and before it allocates, so a refused growth counts nothing,
and a growth the count refuses returns its charge and allocates
nothing.
Sourcepub fn try_count_work(&self, bytes: u64) -> bool
pub fn try_count_work(&self, bytes: u64) -> bool
Counts bytes of work done if the bound holds them, in one atomic
check-and-add as Self::count_decode, and whether it did. A false
counts nothing and records no refusal: a direct read
(crate::ObjectRef::emit_typetree) then leaves the object to the
full reader, which meets the refusal itself.
Sourcepub fn work_used_up(&self) -> Option<WorkPast>
pub fn work_used_up(&self) -> Option<WorkPast>
Whether this open’s work has passed its allowance: the work done and
the allowance when it has, None while it has not. A status, not an
error: the core turns it into its refusal of new work
(LimitKind::DecodeWork) where it refuses that work, through
LimitError::refused, which counts under CR8’s test feature (round
4: this query returned the LimitError itself, uncounted, so a
caller’s code could hand the core a refusal no counter saw). The
allowance is inclusive, as Self::count_decode admits work: work
that lands exactly on it is within it, and what follows is refused by
count_decode itself. Only work counted past the bound (add_work,
unchecked: a detection’s refused chunk, what a refused computation was
granted) passes it, so the refusal’s work is always past the bound
(limit DecodeWork: <work> > <bound>).
Sourcepub fn granted(&self) -> u64
pub fn granted(&self) -> u64
Every byte this meter has granted since it was made, returned or not.
Sourcepub fn unlimited() -> Arc<Self> ⓘ
pub fn unlimited() -> Arc<Self> ⓘ
A meter with no bound and no budget, for data that is not an input’s:
a TPK’s trees, a caller’s nodes= rows, tests.
Sourcepub fn used(&self) -> u64
pub fn used(&self) -> u64
Bytes charged to the input and not yet returned, by every open of it.
Sourcepub fn reservation(&self) -> Reservation
pub fn reservation(&self) -> Reservation
How the budget books this meter’s charges.