Struct Builder

pub struct Builder { /* private fields */ }

Configure length delimited LengthDelimitedCodecs.

Builder enables constructing configured length delimited codecs. Note that not all configuration settings apply to both encoding and decoding. See the documentation for specific methods for more detail.

Note that the if the value of Builder::max_frame_length becomes larger than what can actually fit in Builder::length_field_length, it will be clipped to the maximum value that can fit.

Implementations

impl Builder

pub fn new() -> Builder

Creates a new length delimited codec builder with default configuration values.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .length_field_offset(0)
    .length_field_type::<u16>()
    .length_adjustment(0)
    .num_skip(0)
    .new_read(io);

pub fn big_endian(&mut self) -> &mut Self

Read the length field as a big endian integer

This is the default setting.

This configuration option applies to both encoding and decoding.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .big_endian()
    .new_read(io);

pub fn little_endian(&mut self) -> &mut Self

Read the length field as a little endian integer

The default setting is big endian.

This configuration option applies to both encoding and decoding.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .little_endian()
    .new_read(io);

pub fn native_endian(&mut self) -> &mut Self

Read the length field as a native endian integer

The default setting is big endian.

This configuration option applies to both encoding and decoding.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .native_endian()
    .new_read(io);

pub fn max_frame_length(&mut self, val: usize) -> &mut Self

Sets the max frame length in bytes

This configuration option applies to both encoding and decoding. The default value is 8MB.

When decoding, the length field read from the byte stream is checked against this setting before any adjustments are applied. When encoding, the length of the submitted payload is checked against this setting.

When frames exceed the max length, an io::Error with the custom value of the LengthDelimitedCodecError type will be returned.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .max_frame_length(8 * 1024 * 1024)
    .new_read(io);

pub fn length_field_type<T: LengthFieldType>(&mut self) -> &mut Self

Sets the unsigned integer type used to represent the length field.

The default type is u32. The max type is u64 (or usize on 64-bit targets).

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .length_field_type::<u32>()
    .new_read(io);

Unlike Builder::length_field_length, this does not fail at runtime and instead produces a compile error:

LengthDelimitedCodec::builder()
    .length_field_type::<u128>()
    .new_read(io);

pub fn length_field_length(&mut self, val: usize) -> &mut Self

Sets the number of bytes used to represent the length field

The default value is 4. The max value is 8.

This configuration option applies to both encoding and decoding.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .length_field_length(4)
    .new_read(io);

pub fn length_field_offset(&mut self, val: usize) -> &mut Self

Sets the number of bytes in the header before the length field

This configuration option only applies to decoding.

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .length_field_offset(1)
    .new_read(io);

pub fn length_adjustment(&mut self, val: isize) -> &mut Self

Delta between the payload length specified in the header and the real payload length

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .length_adjustment(-2)
    .new_read(io);

pub fn num_skip(&mut self, val: usize) -> &mut Self

Sets the number of bytes to skip before reading the payload

Default value is length_field_len + length_field_offset

This configuration option only applies to decoding

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .num_skip(4)
    .new_read(io);

pub fn new_codec(&self) -> LengthDelimitedCodec

Create a configured length delimited LengthDelimitedCodec

Examples

use tokio_util::codec::LengthDelimitedCodec;
LengthDelimitedCodec::builder()
    .length_field_offset(0)
    .length_field_type::<u16>()
    .length_adjustment(0)
    .num_skip(0)
    .new_codec();

pub fn new_read<T>(&self, upstream: T) -> FramedRead<T, LengthDelimitedCodec>

where T: AsyncRead,

Create a configured length delimited FramedRead

Examples

use tokio_util::codec::LengthDelimitedCodec;

LengthDelimitedCodec::builder()
    .length_field_offset(0)
    .length_field_type::<u16>()
    .length_adjustment(0)
    .num_skip(0)
    .new_read(io);

pub fn new_write<T>(&self, inner: T) -> FramedWrite<T, LengthDelimitedCodec>

where T: AsyncWrite,

Create a configured length delimited FramedWrite

Examples

LengthDelimitedCodec::builder()
    .length_field_type::<u16>()
    .new_write(io);

pub fn new_framed<T>(&self, inner: T) -> Framed<T, LengthDelimitedCodec>

where T: AsyncRead + AsyncWrite,

Create a configured length delimited Framed

Examples

LengthDelimitedCodec::builder()
    .length_field_type::<u16>()
    .new_framed(io);

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

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

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.

impl Copy for Builder