Struct s2n_quic_core::buffer::ReceiveBuffer

pub struct ReceiveBuffer { /* private fields */ }

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

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

ReceiveBuffer 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_transport::buffer::ReceiveBuffer;

let mut buffer = ReceiveBuffer::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 ReceiveBuffer

pub fn new() -> ReceiveBuffer

Creates a new ReceiveBuffer

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<(), ReceiveBufferError>

Pushes a slice at a certain offset

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

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

pub fn skip(&mut self, len: usize) -> Result<(), ReceiveBufferError>

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 copy_into_buf<B: BufMut>(&mut self, buf: &mut B) -> usize

Copies all the available buffered data into the provided buf’s remaining capacity.

This method is slightly more efficient than Self::pop when the caller ends up copying the buffered data into another slice, since it avoids a refcount increment/decrement on the contained BytesMut.

The total number of bytes copied is returned.

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 ReceiveBuffer

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

Formats the value using the given formatter.

impl Default for ReceiveBuffer

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for ReceiveBuffer

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl StructuralPartialEq for ReceiveBuffer