Module iobuf 

Buffer types for I/O operations.

IoBuf and IoBufMut store readable/writable cursor state directly in the public handle, so the Buf and BufMut hot paths are simple pointer/length arithmetic. Allocation ownership lives in a compact owner word, and owner.rs documents the owner model.

Runtime-owned heap buffers allocate exactly the requested size and alignment (IoBufMut::with_capacity requests byte alignment). While one handle owns such a buffer, its owner word describes the allocation and nothing else is allocated, unless the layout or the spare capacity left at freeze is too large for the word. The first clone, slice, or partial split allocates one small shared owner record. Caller-supplied Vec<u8> values are adopted into the same native form without copying. Caller-supplied Bytes values are held zero-copy by an owner record that keeps the Bytes alive.

Throughout this module, “native” means runtime-owned storage whose owner supports zero-copy mutable recovery through IoBuf::try_into_mut: heap allocations and adopted vecs, as opposed to external Bytes and 'static views.

Conversions

Every From conversion into IoBuf or IoBufs is zero-copy. A conversion from a byte source (Vec<u8>, Bytes, BytesMut, IoBufMut, or a 'static slice) allocates at most one small owner record. When a BytesMut still owns its vector directly and has spare capacity, freezing it also allocates a shared-ownership record. Collecting existing chunks into IoBufs, from IoBuf collections or an IoBufsMut, allocates chunk storage only for four or more chunks. It allocates no owner record, except where freezing an IoBufsMut chunk does (see IoBufMut::freeze).

Conversions into IoBufMut or IoBufsMut reuse the source allocation where it can back a mutable handle and copy into a new one otherwise. Reusing a Bytes or BytesMut keeps its whole allocation as the capacity and moves readable bytes that start past its beginning to the front. Each mutable conversion, and each conversion out of the handles, documents its cost on its impl.

Public types:

• IoBuf: Immutable byte buffer
• IoBufMut: Mutable byte buffer
• IoBufs: Container for one or more immutable buffers
• IoBufsMut: Container for one or more mutable buffers
• Builder: Assembles IoBufs from inline writes and zero-copy pieces

Examples

The core lifecycle: fill a fixed-capacity mutable buffer, freeze it into cheaply cloneable immutable views, and recover the mutable handle (with its spare capacity) once the views are gone:

use commonware_runtime::{Buf, BufMut, IoBuf, IoBufMut};

let mut buf = IoBufMut::with_capacity(8);
buf.put_slice(b"abcdef");

let frozen: IoBuf = buf.freeze();
let head = frozen.slice(..3);
assert_eq!(head, b"abc"[..]);

// A live view shares the owner, so recovery declines.
let frozen = frozen.try_into_mut().unwrap_err();
drop(head);

// Once the view is gone, recovery returns the mutable handle with its
// spare capacity.
let mut recovered = frozen.try_into_mut().unwrap();
assert_eq!(recovered.as_ref(), b"abcdef");
assert_eq!(recovered.capacity(), 8);
recovered.put_slice(b"gh");

Structs

Builder

Assembles IoBufs from a mix of inline writes and zero-copy pieces.

IoBuf

Immutable byte buffer.

IoBufMut

Mutable byte buffer.

IoBufs

Container for one or more immutable buffers.

IoBufsMut

Container for one or more mutable buffers.

Traits

EncodeExt

Extension trait for encoding values that implement Write and EncodeSize into IoBufs.