created_at2018-03-15 15:40:07.957947
updated_at2021-11-21 17:44:44.885799
descriptionUtilities for creating async codecs
Josh Robson Chase (jrobsonchase)



Async Encode/Decode helpers

For prior art, see tokio-codec. This borrows many of the ideas that originated there, though with a simpler and no_std-compatible approach. No allocation is strictly required by implementers of the [Encode] or [Decode] traits, making them suitable for embedded applications.


Encoders are types that implement the [Encode] trait. Consumers of this trait will provide an Item to be encoded, along with a buffer into which the resulting bytes should be placed. The Encoder may return one of three from this operation:

  • EncodeResult::Ok(n): The item was successfully encodeded into the provided buffer and took n bytes.
  • EncodeResult::Err(e): There was an unrecoverable error encoding the item. Subsequent calls with the same item should return the same error.
  • EncodeResult::Overflow(n): The item could be encoded, but the encoded representation would overflow the buffer. If n > 0, then a buffer of length n is required to hold the serialized item.

Upon an Overflow result, the caller should allocate a bigger buffer (if possible), and attempt the operation again. Encode implementations may keep a previously encoded Item in an internal buffer to make re-attempted encodings cheaper. If this approach is used, the [Encode::reset] method must also be implemented.


Decoders implement the [Decode] trait. To decode an Item, callers provide the decoder with a buffer containing bytes from the stream. The decoder returns a usize indicating that it consumed some number of bytes from the buffer, along with one of three results:

  • DecodeResult::Ok(item): The item was successfully decoded
  • DecodeResult::Err(e): An error e arose when decoding the item. This does not necessarily invalidate the stream.
  • DecodeResult::UnexpectedEnd: Not enough data to decode yet, caller should read more and try again with more bytes.

Decoders are free to consume bytes in-line with returning UnexpectedEnd results and keep a running internal buffer of what's been read so far, or they may opt for consuming the bytes for an Item all at once. They should consume bytes in the error case as well so that the caller doesn't provide the same bad data twice.


The [Framed] type provides a wrapper for AsyncRead + AsyncWrite streams that applies an Encode + Decode object to create an async Stream + Sink of Items.

version documentation license


Licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Commit count: 29

cargo fmt