Required Methods

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

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

This method is called by FramedRead whenever bytes are ready to be parsed. The provided buffer of bytes is what's been read so far, and this instance of Decode can determine whether an entire frame is in the buffer and is ready to be returned.

If an entire frame is available, then this instance will remove those bytes from the buffer provided and return them as a decoded frame. Note that removing bytes from the provided buffer doesn't always necessarily copy the bytes, so this should be an efficient operation in most circumstances.

If the bytes look valid, but a frame isn't fully available yet, then Ok(None) is returned. This indicates to the Framed instance that it needs to read some more bytes before calling this method again.

Note that the bytes provided may be empty. If a previous call to decode consumed all the bytes in the buffer then decode will be called again until it returns Ok(None), indicating that more bytes need to be read.

Finally, if the bytes in the buffer are malformed then an error is returned indicating why. This informs Framed that the stream is now corrupt and should be terminated.

Buffer management

Before returning from the function, implementations should ensure that the buffer has appropriate capacity in anticipation of future calls to decode. Failing to do so leads to inefficiency.

For example, if frames have a fixed length, or if the length of the current frame is known from a header, a possible buffer management strategy is:

# use std::io;
#
# use bytes::BytesMut;
# use tokio_util::codec::Decoder;
#
# struct MyCodec;
#
impl Decoder for MyCodec {
    // ...
    # type Item = BytesMut;
    # type Error = io::Error;

    fn decode(&mut self, src: &mut BytesMut) -> Result<Option<Self::Item>, Self::Error> {
        // ...

        // Reserve enough to complete decoding of the current frame.
        let current_frame_len: usize = 1000; // Example.
        // And to start decoding the next frame.
        let next_frame_header_len: usize = 10; // Example.
        src.reserve(current_frame_len + next_frame_header_len);

        return Ok(None);
    }
}

An optimal buffer management strategy minimizes reallocations and over-allocations.