Struct AsyncFixedBuf

pub struct AsyncFixedBuf<const SIZE: usize>(/* private fields */);

A newtype that wraps FixedBuf and implements tokio::io::AsyncRead and tokio::io::AsyncWrite.

It also has async versions of FixedBuf’s io functions.

Implementations

impl<const SIZE: usize> AsyncFixedBuf<SIZE>

pub const fn new() -> Self

Creates a new FixedBuf and wraps it in an AsyncFixedBuf.

See FixedBuf::new for details.

pub fn into_inner(self) -> FixedBuf<SIZE>

Drops the struct and returns its internal FixedBuf.

pub fn empty(mem: [u8; SIZE]) -> Self

Makes a new empty buffer.

Consumes mem and uses it as the internal memory array.

pub fn filled(mem: [u8; SIZE]) -> Self

Makes a new full buffer containing the bytes in mem. Reading the buffer will return the bytes in mem.

Consumes mem and uses it as the internal memory array.

pub async fn copy_once_from<R: AsyncRead + Unpin + Send>( &mut self, reader: &mut R, ) -> Result<usize, Error>

Reads from reader once and writes the data into the buffer.

Returns InvalidData if there is no empty space in the buffer. See shift.

pub async fn read_frame<R, F>( &mut self, reader: &mut R, deframer_fn: F, ) -> Result<Option<&[u8]>, Error>

where R: AsyncRead + Unpin + Send, F: Fn(&[u8]) -> Result<Option<(Range<usize>, usize)>, MalformedInputError>,

Async version of FixedBuf::read_frame.

Methods from Deref<Target = FixedBuf<SIZE>>

pub fn len(&self) -> usize

Returns the number of unread bytes in the buffer.

Example:

let mut buf: FixedBuf<16> = FixedBuf::new();
assert_eq!(0, buf.len());
buf.write_str("abc");
assert_eq!(3, buf.len());
buf.read_bytes(2);
assert_eq!(1, buf.len());
buf.shift();
assert_eq!(1, buf.len());
buf.read_all();
assert_eq!(0, buf.len());

pub fn is_empty(&self) -> bool

Returns true if there are unread bytes in the buffer.

Example:

let mut buf: FixedBuf<16> = FixedBuf::new();
assert!(buf.is_empty());
buf.write_str("abc").unwrap();
assert!(!buf.is_empty());
buf.read_all();
assert!(buf.is_empty());

pub fn clear(&mut self)

Discards all data in the buffer.

pub fn escape_ascii(&self) -> String

Copies all readable bytes to a string. Includes printable ASCII characters as-is. Converts non-printable characters to strings like “\n” and “\x19”.

Uses core::ascii::escape_default(https://doc.rust-lang.org/core/ascii/fn.escape_default.html internally to escape each byte.

This function is useful for printing byte slices to logs and comparing byte slices in tests.

Example test:

use fixed_buffer::FixedBuf;
let mut buf: FixedBuf<8> = FixedBuf::new();
buf.write_str("abc");
buf.write_str("€");
assert_eq!("abc\\xe2\\x82\\xac", buf.escape_ascii());

pub fn mem(&self) -> &[u8]

Borrows the entire internal memory buffer. This is a low-level function.

pub fn readable(&self) -> &[u8]

Returns the slice of readable bytes in the buffer. After processing some bytes from the front of the slice, call read to consume the bytes.

This is a low-level method. You probably want to use std::io::Read::read or tokio::io::AsyncReadExt::read , implemented for FixedBuffer in fixed_buffer_tokio::AsyncReadExt.

pub fn read_byte(&mut self) -> u8

Reads a single byte from the buffer.

Panics if the buffer is empty.

pub fn try_read_byte(&mut self) -> Option<u8>

Reads a single byte from the buffer.

Returns None if the buffer is empty.

pub fn read_bytes(&mut self, num_bytes: usize) -> &[u8]

Reads bytes from the buffer.

Panics if the buffer does not contain enough bytes.

pub fn try_read_bytes(&mut self, num_bytes: usize) -> Option<&[u8]>

Reads bytes from the buffer.

Returns None if the buffer does not contain num_bytes bytes.

pub fn read_all(&mut self) -> &[u8]

Reads all the bytes from the buffer.

The buffer becomes empty and subsequent writes can fill the whole buffer.

pub fn read_and_copy_bytes(&mut self, dest: &mut [u8]) -> usize

Reads bytes from the buffer and copies them into dest.

Returns the number of bytes copied.

Returns 0 when the buffer is empty or dest is zero-length.

pub fn try_read_exact(&mut self, dest: &mut [u8]) -> Option<()>

Reads byte from the buffer and copies them into dest, filling it, and returns ().

Returns None if the buffer does not contain enough bytes tp fill dest.

Returns () if dest is zero-length.

pub fn try_parse<R, F>(&mut self, f: F) -> Option<R>

where F: FnOnce(&mut FixedBuf<SIZE>) -> Option<R>,

Try to parse the buffer contents with f.

f must return None to indicate that the buffer contains an incomplete data record. When try_parse returns None, the caller should add more data to the buffer and call try_parse again.

Undoes any reads that f made to the buffer if it returns None.

f should not write to the buffer. If f writes to the buffer and then returns None, the buffer’s contents will become corrupted.

Example

#[derive(Debug)]
enum ReadError {
    BufferFull,
    EOF,
    TooLong,
    NotUtf8,
}

fn parse_record<const SIZE: usize>(buf: &mut FixedBuf<SIZE>)
-> Option<Result<String, ReadError>>
{
    let len = buf.try_read_byte()? as usize;
    if len > SIZE - 1 {
        return Some(Err(ReadError::TooLong));
    }
    let bytes = buf.try_read_bytes(len)?.to_vec();
    Some(String::from_utf8(bytes)
        .map_err(|_| ReadError::NotUtf8))
}

let mut buf: FixedBuf<16> = FixedBuf::new();
loop {
    // Try reading bytes into the buffer.
    match read_input(&mut buf) {
        Err(ReadError::EOF) if buf.is_empty() => break,
        other => other?,
    }
    // Try parsing bytes into records.
    loop {
        if let Some(result) = buf.try_parse(parse_record) {
            let record = result?;
            process_record(record)?;
        } else {
            // Stop parsing and try reading more bytes.
            break;
        }
    }
}

pub fn copy_once_from<R>(&mut self, reader: &mut R) -> Result<usize, Error>

where R: Read,

Reads from reader once and writes the data into the buffer.

Returns InvalidData if there is no empty space in the buffer. See shift.

pub fn write_str(&mut self, s: &str) -> Result<(), NotEnoughSpaceError>

Writes s into the buffer, after any unread bytes.

Returns Err if the buffer doesn’t have enough free space at the end for the whole string.

See shift.

Example:

let mut buf: FixedBuf<8> = FixedBuf::new();
buf.write_str("123").unwrap();
buf.write_str("456").unwrap();
assert_eq!("123456", buf.escape_ascii());
buf.write_str("78").unwrap();
buf.write_str("9").unwrap_err();  // End of buffer is full.

pub fn write_bytes(&mut self, data: &[u8]) -> Result<usize, NotEnoughSpaceError>

Tries to write data into the buffer, after any unread bytes.

Returns Ok(data.len()) if it wrote all of the bytes.

Returns NotEnoughSpaceError if the buffer doesn’t have enough free space at the end for all of the bytes.

See shift.

Example:

let mut buf: FixedBuf<8> = FixedBuf::new();
assert_eq!(3, buf.write_bytes("123".as_bytes()).unwrap());
assert_eq!(3, buf.write_bytes("456".as_bytes()).unwrap());
assert_eq!("123456", buf.escape_ascii());
assert_eq!(2, buf.write_bytes("78".as_bytes()).unwrap());  // Fills buffer.
buf.write_bytes("9".as_bytes()).unwrap_err();  // Error, buffer is full.

pub fn writable(&mut self) -> &mut [u8]

Returns the writable part of the buffer.

To use this, first modify bytes at the beginning of the slice. Then call wrote(usize) to commit those bytes into the buffer and make them available for reading.

Returns an empty slice when the end of the buffer is full.

See shift.

This is a low-level method. You probably want to use std::io::Write::write or tokio::io::AsyncWriteExt::write, implemented for FixedBuffer in fixed_buffer_tokio::AsyncWriteExt.

Example:

let mut buf: FixedBuf<8> = FixedBuf::new();
buf.writable()[0] = 'a' as u8;
buf.writable()[1] = 'b' as u8;
buf.writable()[2] = 'c' as u8;
buf.wrote(3);
assert_eq!("abc", buf.escape_ascii());

pub fn wrote(&mut self, num_bytes: usize)

Commits bytes into the buffer. Call this after writing to the front of the writable slice.

This is a low-level method.

Panics when there is not num_bytes free at the end of the buffer.

See writable().

pub fn shift(&mut self)

Recovers buffer space.

The buffer is not circular. After you read bytes, the space at the beginning of the buffer is unused. Call this method to move unread data to the beginning of the buffer and recover the space. This makes the free space available for writes, which go at the end of the buffer.

pub fn deframe<F>( &mut self, deframer_fn: F, ) -> Result<Option<Range<usize>>, Error>

where F: Fn(&[u8]) -> Result<Option<(Range<usize>, usize)>, MalformedInputError>,

This is a low-level function. Use read_frame instead.

Calls deframer_fn to check if the buffer contains a complete frame. Consumes the frame bytes from the buffer and returns the range of the frame’s contents in the internal memory.

Use mem to immutably borrow the internal memory and construct the slice with &buf.mem()[range]. This is necessary because deframe borrows self mutably but read_frame needs to borrow it immutably and return a slice.

Returns None if the buffer is empty or contains an incomplete frame.

Returns InvalidData when deframer_fn returns an error.

pub fn read_frame<R, F>( &mut self, reader: &mut R, deframer_fn: F, ) -> Result<Option<&[u8]>, Error>

where R: Read, F: Fn(&[u8]) -> Result<Option<(Range<usize>, usize)>, MalformedInputError>,

Reads from reader into the buffer.

After each read, calls deframer_fn to check if the buffer now contains a complete frame. Consumes the frame bytes from the buffer and returns a slice with the frame contents.

Returns None when reader reaches EOF and the buffer is empty.

Returns UnexpectedEof when reader reaches EOF and the buffer contains an incomplete frame.

Returns InvalidData when deframer_fn returns an error or the buffer fills up.

Calls shift before reading.

Provided deframer functions:

• deframe_line
• deframe_crlf

Example

let mut buf: FixedBuf<32> = FixedBuf::new();
let mut input = std::io::Cursor::new(b"aaa\r\nbbb\n\nccc\n");
loop {
  if let Some(line) =
      buf.read_frame(&mut input, deframe_line).unwrap() {
    println!("{}", escape_ascii(line));
  } else {
    // EOF.
    break;
  }
}
// Prints:
// aaa
// bbb
//
// ccc

Deframer Function deframe_fn

Checks if data contains an entire frame.

Never panics.

Returns Err(MalformedInputError) if data contains a malformed frame.

Returns Ok(None) if data contains an incomplete frame. The caller will read more data and call deframe again.

Returns Ok((range, len)) when data contains a complete well-formed frame of length len and contents &data[range].

A frame is a sequence of bytes containing a payload and metadata prefix or suffix bytes. The metadata define where the payload starts and ends. Popular frame protocols include line-delimiting (CSV), hexadecimal length prefix (HTTP chunked transfer encoding), and binary length prefix (TLS).

If the caller removes len bytes from the front of data, then data should start with the next frame, ready to call deframe again.

A line-delimited deframer returns range so that &data[range] contains the entire line without the final b'\n' or b"\r\n". It returns len that counts the bytes of the entire line and the final b'\n' or b"\r\n".

Example

A CRLF-terminated line deframer:

assert_eq!(Ok(None), deframe_crlf(b""));
assert_eq!(Ok(None), deframe_crlf(b"abc"));
assert_eq!(Ok(None), deframe_crlf(b"abc\r"));
assert_eq!(Ok(None), deframe_crlf(b"abc\n"));
assert_eq!(Ok(Some((0..3, 5))), deframe_crlf(b"abc\r\n"));
assert_eq!(Ok(Some((0..3, 5))), deframe_crlf(b"abc\r\nX"));

Trait Implementations

impl<const SIZE: usize> AsyncRead for AsyncFixedBuf<SIZE>

fn poll_read( self: Pin<&mut Self>, _cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<(), Error>>

Attempts to read from the AsyncRead into buf.

impl<const SIZE: usize> AsyncWrite for AsyncFixedBuf<SIZE>

fn poll_write( self: Pin<&mut Self>, _cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut Self>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown( self: Pin<&mut Self>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<const SIZE: usize> Deref for AsyncFixedBuf<SIZE>

type Target = FixedBuf<SIZE>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<const SIZE: usize> DerefMut for AsyncFixedBuf<SIZE>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<const SIZE: usize> Unpin for AsyncFixedBuf<SIZE>