Struct chunked_bytes::ChunkedBytes

pub struct ChunkedBytes { /* fields omitted */ }

A non-contiguous buffer for efficient serialization of data structures.

A ChunkedBytes container has a staging buffer to coalesce small byte sequences of source data, and a queue of byte chunks split off the staging buffer that can be incrementally consumed by an output API such as an object implementing AsyncWrite. Once the number of bytes in the staging buffer reaches a certain configured chunk size, the buffer content is split off to form a new chunk.

Refer to the documentation on the methods available for ChunkedBytes, including the methods of traits Buf and BufMut, for details on working with this container.

Implementations

impl ChunkedBytes

pub fn new() -> Self

Creates a new ChunkedBytes container with the preferred chunk size set to a default value.

pub fn with_preferred_chunk_size(chunk_size: usize) -> Self

Creates a new ChunkedBytes container with the given chunk size to prefer.

pub fn preferred_chunk_size(&self) -> usize

Returns the size this ChunkedBytes container uses as the threshold for splitting off complete chunks.

Note that the size of produced chunks may be larger than the configured value due to the allocation strategy used internally by the implementation. Chunks may also be smaller than the threshold if writing with BufMut methods has been mixed with use of the push_chunk method, or the flush method has been called directly.

pub fn is_empty(&self) -> bool

Returns true if the ChunkedBytes container has no complete chunks and the staging buffer is empty.

pub fn flush(&mut self)

Splits any bytes that are currently in the staging buffer into a new complete chunk. If the staging buffer is empty, this method does nothing.

Most users should not need to call this method. It is called internally when needed by the methods that advance the writing position.

pub fn push_chunk(&mut self, chunk: Bytes)

Appends a Bytes slice to the container without copying the data.

If there are any bytes currently in the staging buffer, they are split to form a complete chunk. Next, the given slice is appended as the next chunk.

pub fn drain_chunks(&mut self) -> DrainChunks

Returns an iterator that removes complete chunks from the ChunkedBytes container and yields the removed chunks as Bytes slice handles. This does not include bytes in the staging buffer.

The chunks are removed even if the iterator is dropped without being consumed until the end. It is unspecified how many chunks are removed if the DrainChunks value is not dropped, but the borrow it holds expires (e.g. due to std::mem::forget).

pub fn into_chunks(self) -> IntoChunks

Consumes the ChunkedBytes container to produce an iterator over its chunks. If there are bytes in the staging buffer, they are yielded as the last chunk.

The memory allocated for IntoChunks may be slightly more than the ChunkedBytes container it consumes. This is an infrequent side effect of making the internal state efficient in general for iteration.

Trait Implementations

impl Buf for ChunkedBytes

fn remaining(&self) -> usize

Returns the number of bytes between the current position and the end of the buffer.

fn has_remaining(&self) -> bool

Returns true if there are any more bytes to consume

fn bytes(&self) -> &[u8]

Returns a slice of the bytes in the first extant complete chunk, or the bytes in the staging buffer if there are no unconsumed chunks.

It is more efficient to use bytes_vectored to gather all the disjoint slices for vectored output, as is done in many specialized implementations of the AsyncWrite::poll_write_buf method.

fn advance(&mut self, cnt: usize)

Advances the reading position by cnt, dropping the Bytes references to any complete chunks that the position has been advanced past and then advancing the starting position of the first remaining chunk. If there are no complete chunks left, the reading position is advanced in the staging buffer, effectively removing the consumed bytes.

Panics

This function may panic when cnt > self.remaining().

fn bytes_vectored<'a>(&'a self, dst: &mut [IoSlice<'a>]) -> usize

Fills dst sequentially with the slice views of the chunks, then the bytes in the staging buffer if any remain and there is another unfilled entry left in dst. Returns the number of IoSlice entries filled.

fn to_bytes(&mut self) -> Bytes

Consumes remaining bytes inside self and returns new instance of Bytes

fn copy_to_slice(&mut self, dst: &mut [u8])

Copies bytes from self into dst.

fn get_u8(&mut self) -> u8

Gets an unsigned 8 bit integer from self.

fn get_i8(&mut self) -> i8

Gets a signed 8 bit integer from self.

fn get_u16(&mut self) -> u16

Gets an unsigned 16 bit integer from self in big-endian byte order.

fn get_u16_le(&mut self) -> u16

Gets an unsigned 16 bit integer from self in little-endian byte order.

fn get_i16(&mut self) -> i16

Gets a signed 16 bit integer from self in big-endian byte order.

fn get_i16_le(&mut self) -> i16

Gets a signed 16 bit integer from self in little-endian byte order.

fn get_u32(&mut self) -> u32

Gets an unsigned 32 bit integer from self in the big-endian byte order.

fn get_u32_le(&mut self) -> u32

Gets an unsigned 32 bit integer from self in the little-endian byte order.

fn get_i32(&mut self) -> i32

Gets a signed 32 bit integer from self in big-endian byte order.

fn get_i32_le(&mut self) -> i32

Gets a signed 32 bit integer from self in little-endian byte order.

fn get_u64(&mut self) -> u64

Gets an unsigned 64 bit integer from self in big-endian byte order.

fn get_u64_le(&mut self) -> u64

Gets an unsigned 64 bit integer from self in little-endian byte order.

fn get_i64(&mut self) -> i64

Gets a signed 64 bit integer from self in big-endian byte order.

fn get_i64_le(&mut self) -> i64

Gets a signed 64 bit integer from self in little-endian byte order.

fn get_u128(&mut self) -> u128

Gets an unsigned 128 bit integer from self in big-endian byte order.

fn get_u128_le(&mut self) -> u128

Gets an unsigned 128 bit integer from self in little-endian byte order.

fn get_i128(&mut self) -> i128

Gets a signed 128 bit integer from self in big-endian byte order.

fn get_i128_le(&mut self) -> i128

Gets a signed 128 bit integer from self in little-endian byte order.

fn get_uint(&mut self, nbytes: usize) -> u64

Gets an unsigned n-byte integer from self in big-endian byte order.

fn get_uint_le(&mut self, nbytes: usize) -> u64

Gets an unsigned n-byte integer from self in little-endian byte order.

fn get_int(&mut self, nbytes: usize) -> i64

Gets a signed n-byte integer from self in big-endian byte order.

fn get_int_le(&mut self, nbytes: usize) -> i64

Gets a signed n-byte integer from self in little-endian byte order.

fn get_f32(&mut self) -> f32

Gets an IEEE754 single-precision (4 bytes) floating point number from self in big-endian byte order.

fn get_f32_le(&mut self) -> f32

Gets an IEEE754 single-precision (4 bytes) floating point number from self in little-endian byte order.

fn get_f64(&mut self) -> f64

Gets an IEEE754 double-precision (8 bytes) floating point number from self in big-endian byte order.

fn get_f64_le(&mut self) -> f64

Gets an IEEE754 double-precision (8 bytes) floating point number from self in little-endian byte order.

impl BufMut for ChunkedBytes

fn remaining_mut(&self) -> usize

Returns the number of bytes that can be written from the current position until the end of the buffer is reached.

unsafe fn advance_mut(&mut self, cnt: usize)

Advances the writing position in the staging buffer.

If the number of bytes accumulated in the staging buffer reaches or exceeds the preferred chunk size, the bytes are split off to form a new complete chunk.

Panics

This function may panic if cnt > self.remaining_mut().

fn bytes_mut(&mut self) -> &mut [MaybeUninit<u8>]

Returns a mutable slice of unwritten bytes available in the staging buffer, starting at the current writing position.

The length of the slice may be larger than the preferred chunk size due to the allocation strategy used internally by the implementation.

fn has_remaining_mut(&self) -> bool

Returns true if there is space in self for more bytes.

fn bytes_vectored_mut(&'a mut self, dst: &mut [IoSliceMut<'a>]) -> usize

Fills dst with potentially multiple mutable slices starting at self's current position.

fn put<T>(&mut self, src: T) where
    T: Buf, 

Transfer bytes into self from src and advance the cursor by the number of bytes written.

fn put_slice(&mut self, src: &[u8])

Transfer bytes into self from src and advance the cursor by the number of bytes written.

fn put_u8(&mut self, n: u8)

Writes an unsigned 8 bit integer to self.

fn put_i8(&mut self, n: i8)

Writes a signed 8 bit integer to self.

fn put_u16(&mut self, n: u16)

Writes an unsigned 16 bit integer to self in big-endian byte order.

fn put_u16_le(&mut self, n: u16)

Writes an unsigned 16 bit integer to self in little-endian byte order.

fn put_i16(&mut self, n: i16)

Writes a signed 16 bit integer to self in big-endian byte order.

fn put_i16_le(&mut self, n: i16)

Writes a signed 16 bit integer to self in little-endian byte order.

fn put_u32(&mut self, n: u32)

Writes an unsigned 32 bit integer to self in big-endian byte order.

fn put_u32_le(&mut self, n: u32)

Writes an unsigned 32 bit integer to self in little-endian byte order.

fn put_i32(&mut self, n: i32)

Writes a signed 32 bit integer to self in big-endian byte order.

fn put_i32_le(&mut self, n: i32)

Writes a signed 32 bit integer to self in little-endian byte order.

fn put_u64(&mut self, n: u64)

Writes an unsigned 64 bit integer to self in the big-endian byte order.

fn put_u64_le(&mut self, n: u64)

Writes an unsigned 64 bit integer to self in little-endian byte order.

fn put_i64(&mut self, n: i64)

Writes a signed 64 bit integer to self in the big-endian byte order.

fn put_i64_le(&mut self, n: i64)

Writes a signed 64 bit integer to self in little-endian byte order.

fn put_u128(&mut self, n: u128)

Writes an unsigned 128 bit integer to self in the big-endian byte order.

fn put_u128_le(&mut self, n: u128)

Writes an unsigned 128 bit integer to self in little-endian byte order.

fn put_i128(&mut self, n: i128)

Writes a signed 128 bit integer to self in the big-endian byte order.

fn put_i128_le(&mut self, n: i128)

Writes a signed 128 bit integer to self in little-endian byte order.

fn put_uint(&mut self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in big-endian byte order.

fn put_uint_le(&mut self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in the little-endian byte order.

fn put_int(&mut self, n: i64, nbytes: usize)

Writes a signed n-byte integer to self in big-endian byte order.

fn put_int_le(&mut self, n: i64, nbytes: usize)

Writes a signed n-byte integer to self in little-endian byte order.

fn put_f32(&mut self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in big-endian byte order.

fn put_f32_le(&mut self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in little-endian byte order.

fn put_f64(&mut self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in big-endian byte order.

fn put_f64_le(&mut self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in little-endian byte order.

impl Debug for ChunkedBytes

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

Formats the value using the given formatter.

impl Default for ChunkedBytes

fn default() -> Self

Returns the "default value" for a type.