Struct ReadBuf 

pub struct ReadBuf { /* private fields */ }

Flat byte slab for inbound protocol parsing.

The I/O layer reads bytes into the slab via spare() + filled(). The protocol parser walks it via data() + advance(). When all data is consumed, cursors reset to the pre-padding offset — no memmove.

Fixed capacity. No growth.

Layout

[ pre_padding | usable capacity                        | post_padding ]
              ^                                        ^
              head/tail start here                     end of usable

Pre-padding: reserved bytes before the data region. Protocol layers can use this for header reassembly (e.g., uWS writes spilled header bytes backward into pre-padding). Accessible via pre_padding_mut().

Post-padding: reserved bytes after the data region. SIMD operations may overrun by up to alignment width. ReadBuf guarantees this space exists but doesn’t manage it.

Examples

use nexus_net::buf::ReadBuf;

let mut buf = ReadBuf::with_capacity(4096);

// I/O: read bytes into spare region
let spare = buf.spare();
spare[..5].copy_from_slice(b"Hello");
buf.filled(5);

// Parse: consume from data region
assert_eq!(buf.data(), b"Hello");
buf.advance(5);
assert!(buf.is_empty()); // cursors auto-reset

Implementations

impl ReadBuf

pub fn new(capacity: usize, pre_padding: usize, post_padding: usize) -> ReadBuf

Create a ReadBuf with explicit padding.

Total allocation: pre_padding + capacity + post_padding. The buffer is fixed-size — it never reallocates.

pub fn with_capacity(capacity: usize) -> ReadBuf

Convenience: capacity only, zero padding.

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

Unconsumed bytes. Always a single contiguous slice.

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

Mutable access to unconsumed bytes. For in-place operations like XOR unmasking.

pub fn advance(&mut self, n: usize)

Consume n bytes from the front.

If the buffer becomes empty after advance, resets head and tail to pre_padding offset (free — no memmove, just cursor reset).

Panics

Panics if n > self.len().

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

Writable tail region for direct socket reads.

let n = socket.read(buf.spare())?;
buf.filled(n);

Returns buf[tail .. pre_padding + capacity]. May be empty if tail has reached the capacity boundary.

pub fn filled(&mut self, n: usize)

Commit n bytes written into spare().

Panics

Panics if n would push tail past capacity boundary.

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

Mutable access to the pre-padding region (bytes before head).

Returns buf[0..head]. Protocol layers can use this for header reassembly — e.g., writing spilled header bytes backward so the parser sees a contiguous header without memmove.

The returned slice includes both the original pre-padding AND any consumed-but-not-reset space before head.

pub fn len(&self) -> usize

Bytes of unconsumed data.

pub fn is_empty(&self) -> bool

Whether the buffer is empty.

pub fn capacity(&self) -> usize

Usable capacity (excluding padding).

pub fn remaining(&self) -> usize

Writable space at the tail (same as spare().len()).

pub fn clear(&mut self)

Discard all data. Cursors reset to pre_padding offset.

pub fn consumed(&self) -> usize

Bytes consumed from the front (how far head has advanced from start).

Useful for determining when to proactively compact().

pub fn compact(&mut self)

Reclaim consumed space by moving unconsumed data to the front.

Call when spare() is empty but there is consumed space before head that can be reclaimed. The unconsumed data (typically a partial frame) is moved to the pre_padding offset.

Cost: O(unconsumed bytes). For a partial frame this is typically a few hundred bytes — under 100ns.

No-op if the buffer is already at the front or empty.