Struct tokio_util::codec::length_delimited::Builder

source ·
pub struct Builder { /* private fields */ }
Available on crate feature codec only.
Expand description

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§

source§

impl Builder

source

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);
source

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);
source

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);
source

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);
source

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);
source

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);
source

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);
source

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);
source

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);
source

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);
source

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();
source

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);
source

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);
source

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§

source§

impl Clone for Builder

source§

fn clone(&self) -> Builder

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Builder

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Builder

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl Copy for Builder

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> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

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

source§

type Error = Infallible

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

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

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.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more