pub struct DecodeBuf { /* private fields */ }Expand description
A decoder’s output buffer that pays before it grows.
A codec writes a block’s output here and nowhere else
(crate::codec::BlockCodec::decode); the core’s other byte buffers
(a path read, the writer’s output) use it too. Every growth first checks
the current segment’s cap, then charges the new allocation to the input’s
meter (which books it with the budget), and only then grows; a refused
growth allocates nothing. Capacity grows geometrically, never past the
current segment’s end (its start and its cap: room no write may use is
never allocated, review round 13), nor, while what is needed fits it,
past the run’s declared end: the block’s start, the size
Self::begin_block was given, and what the run’s next blocks declare
as far as its reader has read ahead (set_ahead, which the crate’s
bundle reader calls). Room a well-formed run never writes is never
allocated, so a block decoded in windows ends at its declared size, and
a run of blocks doubles, ending at its last block’s end. A refused
doubling is asked again with half the room past the size needed, down
to exactly that size (crate::limits::MeteredVec’s growth). A block
that writes past that declared end (an LZMA stream that ignores its
size) grows geometrically from there, to the segment’s end.
Segments. A run of several blocks is one buffer, but each block has
its own cap (crate::limits::Limits::max_block_output): the caller
starts each block with Self::begin_block, and a block that writes past
its own cap fails there, whatever the run’s size. Every decode is charged
(a first decode, a re-decode, a measuring decode): the meter counts what is
held, not what was first seen. A block’s segment (capped by
LimitKind::BlockOutput) also counts every byte written into it
(Self::extend_from_slice, Self::grow_zeroed) as the decode work
of its meter’s open (crate::limits::Limits::max_decode_work), which
is never returned, so a block decoded again and again (a failing block
read for every entry, a span re-decoded for every range) stops there even
though each attempt returns its memory. The count is of writes, not of
growths: a buffer sized up front, a scratch buffer reused across decodes
and output written in small pieces count every byte (round 6: growths
alone were counted, so all three decoded without bound). Room made ahead
(Self::new’s initial, Self::reserve) is memory, charged, and
counts as work only when it is written. Work counted ahead for what a
decode reads (prepay, the bundle reader’s) is credit its writes use
first.
Drop. A buffer dropped unfinished (a decode that failed) returns its charge with its allocation.
Implementations§
Source§impl DecodeBuf
impl DecodeBuf
Sourcepub fn new(
meter: &Arc<Meter>,
initial: u64,
cap: u64,
cap_kind: LimitKind,
) -> Result<Self, ChargeError>
pub fn new( meter: &Arc<Meter>, initial: u64, cap: u64, cap_kind: LimitKind, ) -> Result<Self, ChargeError>
An empty buffer charging meter, with room for initial bytes (cut
to cap), charged before it is allocated. Its first segment may hold
cap bytes; passing that is a cap_kind limit error.
Sourcepub fn begin_block(&mut self, cap: u64, cap_kind: LimitKind, declared: u64)
pub fn begin_block(&mut self, cap: u64, cap_kind: LimitKind, declared: u64)
Starts a new segment at the current length (the next block of a run):
from here the buffer may grow by at most cap bytes, and its room
grows past declared bytes (the block’s declared size, a growth
hint) only for a write that needs it (type docs).
Sourcepub fn meter(&self) -> &Arc<Meter> ⓘ
pub fn meter(&self) -> &Arc<Meter> ⓘ
The meter this buffer charges: a codec charges what it holds beside its output (an LZMA dictionary) to the same input.
Sourcepub fn segment_cap(&self) -> u64
pub fn segment_cap(&self) -> u64
The cap of the current segment (Self::begin_block’s cap).
Sourcepub fn segment_len(&self) -> usize
pub fn segment_len(&self) -> usize
The bytes written in the current segment (since the last
Self::begin_block).
Sourcepub fn reserve(&mut self, additional: usize) -> Result<(), ChargeError>
pub fn reserve(&mut self, additional: usize) -> Result<(), ChargeError>
Makes room for additional more bytes: the segment’s cap is checked
and the meter charged before the buffer grows. The capacity doubles,
up to the segment’s end (and to the run’s declared end while what is
needed fits it), while the meter can pay for the old and the new
block at once, and grows to exactly what is needed when it cannot.
Room is memory, not work: what is written into it counts
(Self::extend_from_slice).
Sourcepub fn extend_from_slice(&mut self, data: &[u8]) -> Result<(), ChargeError>
pub fn extend_from_slice(&mut self, data: &[u8]) -> Result<(), ChargeError>
Appends data.
Sourcepub fn grow_zeroed(&mut self, n: usize) -> Result<&mut [u8], ChargeError>
pub fn grow_zeroed(&mut self, n: usize) -> Result<&mut [u8], ChargeError>
Appends n zero bytes and returns them for a decoder to fill; cut the
unused tail with Self::truncate. All n count as written.
Sourcepub fn truncate(&mut self, len: usize)
pub fn truncate(&mut self, len: usize)
Cuts the written bytes to len. The allocation and its charge stay
until Self::into_bytes or drop.
Sourcepub fn into_bytes(self) -> Result<Bytes, ChargeError>
pub fn into_bytes(self) -> Result<Bytes, ChargeError>
The output as Bytes that carry their charge (charged_bytes).
A buffer with spare capacity is shrunk to its length, its charge cut
to the smaller block’s (crate::limits::MeteredVec::shrink_to_fit’s
rule): in place, charging nothing more (perf stage 2: the smaller
block was charged beside the old one, which an in-place shrink never
holds); or, for a block that may be mapped given back below 128 KiB
(crate::limits::shrink_moves; review round 13: 10 bytes cut from
room of 1 MiB, as an LZMA block’s first window leaves a short block,
held a page against a charge of 32 bytes), moved to a new block when
the meter can also pay for it while the bytes move, and kept (charged
as it is) when the meter or the allocator refuses that block.