Struct FrameCodec 

pub struct FrameCodec<F> { /* private fields */ }

Available on crate feature bytes only.

A Framer driven over a BytesMut buffer.

Example

use bytes::BytesMut;
use wire_codec::codec::FrameCodec;
use wire_codec::framing::VarintPrefixed;

let mut codec = FrameCodec::new(VarintPrefixed::new());
let mut wire = BytesMut::new();
codec.encode_frame(b"hello", &mut wire).unwrap();
codec.encode_frame(b"world", &mut wire).unwrap();

assert_eq!(&codec.decode_frame(&mut wire).unwrap().unwrap()[..], b"hello");
assert_eq!(&codec.decode_frame(&mut wire).unwrap().unwrap()[..], b"world");
assert_eq!(codec.decode_frame(&mut wire).unwrap(), None);
assert!(wire.is_empty());

Implementations

impl<F: Framer> FrameCodec<F>

pub const fn new(framer: F) -> Self

Wrap framer.

pub const fn framer(&self) -> &F

Borrow the wrapped framer.

pub fn into_inner(self) -> F

Consume the codec and return the wrapped framer.

pub fn reset(&mut self)

Forget the partial-scan progress kept between FrameCodec::decode_frame calls.

The codec assumes the receive buffer only grows at the back between calls, apart from the frames it splits off itself. Call reset when you clear, truncate, or replace the buffer (for example to resynchronise, after Framed::from_parts with a fresh read buffer, or when reusing the codec for a new connection). Progress is also cleared automatically whenever decoding returns an error.

Example

use bytes::BytesMut;
use wire_codec::codec::FrameCodec;
use wire_codec::framing::Delimited;

let mut codec = FrameCodec::new(Delimited::bounded(b"\n").unwrap());
let mut src = BytesMut::from(&b"partial line"[..]);
assert_eq!(codec.decode_frame(&mut src).unwrap(), None);

// Switch to a different stream: drop the buffer and the progress.
src.clear();
codec.reset();
src.extend_from_slice(b"a\nb\n");
assert_eq!(&codec.decode_frame(&mut src).unwrap().unwrap()[..], b"a");

pub fn decode_frame(&mut self, src: &mut BytesMut) -> Result<Option<BytesMut>>

Remove the next complete frame from the front of src and return its payload, or Ok(None) if src does not hold a full frame yet.

Errors

Propagates the framer’s errors. Returns Error::InvalidEncoding if a custom framer violates the Frame contract (zero bytes consumed, or more than the input). src is left untouched on error, and the scan progress is cleared so the caller may discard the buffer and resynchronise.

pub fn decode_frame_eof( &mut self, src: &mut BytesMut, ) -> Result<Option<BytesMut>>

Like FrameCodec::decode_frame, for the end of the stream: once no more input will arrive, leftover bytes that do not form a frame are an error.

Errors

Everything FrameCodec::decode_frame returns, plus Error::UnexpectedEof when src holds a partial frame.

pub fn encode_frame(&mut self, payload: &[u8], dst: &mut BytesMut) -> Result<()>

Append payload as one frame to dst, growing it as needed.

Space is reserved in one step using Framer::max_frame_len. For a custom framer that does not implement it, the codec retries with a doubling scratch region, up to four times the payload size plus 4 KiB.

Errors

Propagates the framer’s errors, or returns Error::BufferFull if a custom framer needs more room than the retry limit. dst is left untouched on error.

Trait Implementations

impl<F: Clone> Clone for FrameCodec<F>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<F: Debug> Debug for FrameCodec<F>

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

Formats the value using the given formatter.

impl<F: Framer> Decoder for FrameCodec<F>

Available on crate feature tokio-util only.

type Item = BytesMut

The type of decoded frames.

type Error = Error

The type of unrecoverable frame decoding errors.

fn decode(&mut self, src: &mut BytesMut) -> Result<Option<BytesMut>>

Attempts to decode a frame from the provided buffer of bytes.

fn decode_eof(&mut self, src: &mut BytesMut) -> Result<Option<BytesMut>>

A default method available to be called when there are no more bytes available to be read from the underlying I/O.

fn framed<T>(self, io: T) -> Framed<T, Self>

where T: AsyncRead + AsyncWrite, Self: Sized,

Provides a Stream and Sink interface for reading and writing to this Io object, using Decode and Encode to read and write the raw data.

impl<F: Framer> Decoder for FrameCodec<F>

Available on crate feature asynchronous-codec only.

type Item = BytesMut

The type of items returned by decode

type Error = Error

The type of decoding errors.

fn decode(&mut self, src: &mut BytesMut) -> Result<Option<BytesMut>>

Decode an item from the src BytesMut into an item

fn decode_eof(&mut self, src: &mut BytesMut) -> Result<Option<BytesMut>>

Called when the input stream reaches EOF, signaling a last attempt to decode

impl<F: Default> Default for FrameCodec<F>

fn default() -> Self

Returns the “default value” for a type.

impl<F: Framer> Encoder for FrameCodec<F>

Available on crate feature asynchronous-codec only.

type Item<'a> = &'a [u8]

The type of items consumed by encode

type Error = Error

The type of encoding errors.

fn encode(&mut self, item: &[u8], dst: &mut BytesMut) -> Result<()>

Encodes an item into the BytesMut provided by dst.

impl<F: Framer> Encoder<&[u8]> for FrameCodec<F>

Available on crate feature tokio-util only.

type Error = Error

The type of encoding errors.

fn encode(&mut self, item: &[u8], dst: &mut BytesMut) -> Result<()>

Encodes a frame into the buffer provided.

impl<F: Framer> Encoder<Bytes> for FrameCodec<F>

Available on crate feature tokio-util only.

type Error = Error

The type of encoding errors.

fn encode(&mut self, item: Bytes, dst: &mut BytesMut) -> Result<()>

Encodes a frame into the buffer provided.

impl<F: Framer> Encoder<BytesMut> for FrameCodec<F>

Available on crate feature tokio-util only.

type Error = Error

The type of encoding errors.

fn encode(&mut self, item: BytesMut, dst: &mut BytesMut) -> Result<()>

Encodes a frame into the buffer provided.

impl<F: Eq> Eq for FrameCodec<F>

impl<F: Hash> Hash for FrameCodec<F>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<F: PartialEq> PartialEq for FrameCodec<F>

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

Equality operator ==.

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

Inequality operator !=.

impl<F: PartialEq> StructuralPartialEq for FrameCodec<F>