Skip to main content

DecodeBuf

Struct DecodeBuf 

Source
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

Source

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.

Source

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).

Source

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.

Source

pub fn segment_cap(&self) -> u64

The cap of the current segment (Self::begin_block’s cap).

Source

pub fn len(&self) -> usize

The bytes written.

Source

pub fn segment_len(&self) -> usize

The bytes written in the current segment (since the last Self::begin_block).

Source

pub fn is_empty(&self) -> bool

Whether nothing was written.

Source

pub fn capacity(&self) -> usize

The allocation.

Source

pub fn charged(&self) -> u64

The bytes charged for this buffer: heap_cost of its capacity.

Source

pub fn as_slice(&self) -> &[u8] ⓘ

The bytes written.

Source

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).

Source

pub fn extend_from_slice(&mut self, data: &[u8]) -> Result<(), ChargeError>

Appends data.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Debug for DecodeBuf

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.