Struct Reassembler

pub struct Reassembler { /* private fields */ }

Reassembler is a buffer structure for combining chunks of bytes in an ordered stream, which might arrive out of order.

Reassembler will accumulate the bytes, and provide them to its users once a contiguous range of bytes at the current position of the stream has been accumulated.

Reassembler is optimized for minimizing memory allocations and for offering it’s users chunks of sizes that minimize call overhead.

If data is received in smaller chunks, only the first chunk will trigger a memory allocation. All other chunks can be copied into the already allocated region.

When users want to consume data from the buffer, the consumable part of the internal receive buffer is split off and passed back to the caller. Due to this chunk being a view onto a reference-counted internal buffer of type BytesMut this is also efficient and does not require additional memory allocation or copy.

Usage

use s2n_quic_core::buffer::Reassembler;

let mut buffer = Reassembler::new();

// write a chunk of bytes at offset 4, which can not be consumed yet
assert!(buffer.write_at(4u32.into(), &[4, 5, 6, 7]).is_ok());
assert_eq!(0, buffer.len());
assert_eq!(None, buffer.pop());

// write a chunk of bytes at offset 0, which allows for consumption
assert!(buffer.write_at(0u32.into(), &[0, 1, 2, 3]).is_ok());
assert_eq!(8, buffer.len());

// Pop chunks. Since they all fitted into a single internal buffer,
// they will be returned in combined fashion.
assert_eq!(&[0u8, 1, 2, 3, 4, 5, 6, 7], &buffer.pop().unwrap()[..]);

Implementations

impl Reassembler

pub fn new() -> Reassembler

Creates a new Reassembler

pub fn is_writing_complete(&self) -> bool

Returns true if the buffer has completely been written to and the final size is known

pub fn is_reading_complete(&self) -> bool

Returns true if the buffer has completely been read and the final size is known

pub fn final_size(&self) -> Option<u64>

Returns the final size of the stream, if known

pub fn len(&self) -> usize

Returns the amount of bytes available for reading. This equals the amount of data that is stored in contiguous fashion at the start of the buffer.

pub fn is_empty(&self) -> bool

Returns true if no bytes are available for reading

pub fn report(&self) -> (usize, usize)

Returns the number of bytes and chunks available for consumption

pub fn write_at(&mut self, offset: VarInt, data: &[u8]) -> Result<(), Error>

Pushes a slice at a certain offset

pub fn write_at_fin(&mut self, offset: VarInt, data: &[u8]) -> Result<(), Error>

Pushes a slice at a certain offset, which is the end of the buffer

pub fn write_reader<R>(&mut self, reader: &mut R) -> Result<(), Error<R::Error>>

where R: Reader + ?Sized,

pub fn skip(&mut self, len: VarInt) -> Result<(), Error>

Advances the read and write cursors and discards any held data

This can be used for copy-avoidance applications where a packet is received in order and doesn’t need to be stored temporarily for future packets to unblock the stream.

pub fn iter(&self) -> impl Iterator<Item = &[u8]>

Iterates over all of the chunks waiting to be received

pub fn drain(&mut self) -> impl Iterator<Item = BytesMut> + '_

Drains all of the currently available chunks

pub fn pop(&mut self) -> Option<BytesMut>

Pops a buffer from the front of the receive queue if available

pub fn pop_watermarked(&mut self, watermark: usize) -> Option<BytesMut>

Pops a buffer from the front of the receive queue, who’s length is always guaranteed to be less than the provided watermark.

pub fn consumed_len(&self) -> u64

Returns the amount of data that had already been consumed from the receive buffer.

pub fn total_received_len(&self) -> u64

Returns the total amount of contiguous received data.

This includes the already consumed data as well as the data that is still buffered and available for consumption.

pub fn reset(&mut self)

Resets the receive buffer.

This will drop all previously received data.

Trait Implementations

impl Debug for Reassembler

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

Formats the value using the given formatter.

impl Default for Reassembler

fn default() -> Reassembler

Returns the “default value” for a type.

impl PartialEq for Reassembler

fn eq(&self, other: &Reassembler) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reader for Reassembler

fn current_offset(&self) -> VarInt

Returns the currently read offset for the stream

fn final_offset(&self) -> Option<VarInt>

Returns the final offset for the stream

fn has_buffered_fin(&self) -> bool

Returns true if the reader has the final offset buffered

fn is_consumed(&self) -> bool

Returns true if the reader is finished producing data

fn skip_until(&mut self, offset: VarInt) -> Result<(), Self::Error>

Skips the data in the reader until offset is reached, or the reader storage is exhausted.

fn with_max_data(&mut self, max_data: VarInt) -> Limit<'_, Self>

Limits the maximum offset that the caller can read from the reader

fn with_read_limit(&mut self, max_buffered_len: usize) -> Limit<'_, Self>

Limits the maximum amount of data that the caller can read from the reader

fn with_empty_buffer(&self) -> Empty<'_, Self>

Return an empty view onto the reader, with no change in current offset

fn with_checks(&mut self) -> Checked<'_, Self>

Enables checking the reader for correctness invariants

impl Skip for Reassembler

fn skip( &mut self, len: VarInt, final_offset: Option<VarInt>, ) -> Result<(), Error>

impl Storage for Reassembler

type Error = Infallible

fn buffered_len(&self) -> usize

Returns the length of the chunk

fn buffer_is_empty(&self) -> bool

Returns if the chunk is empty

fn read_chunk(&mut self, watermark: usize) -> Result<Chunk<'_>, Self::Error>

Reads the current contiguous chunk

fn partial_copy_into<Dest>( &mut self, dest: &mut Dest, ) -> Result<Chunk<'_>, Self::Error>

where Dest: Storage + ?Sized,

Copies the reader into dest, with a trailing chunk of bytes.

fn copy_into<Dest>(&mut self, dest: &mut Dest) -> Result<(), Self::Error>

where Dest: Storage + ?Sized,

Copies the reader into dest.

fn full_copy(&mut self) -> FullCopy<'_, Self>

Forces the entire reader to be copied, even when calling partial_copy_into.

fn track_read(&mut self) -> Tracked<'_, Self>

Tracks the number of bytes read from the storage

impl Writer for Reassembler

fn read_from<R>(&mut self, reader: &mut R) -> Result<(), Error<R::Error>>

where R: Reader + ?Sized,

impl StructuralPartialEq for Reassembler