Module iobuf 

Buffer types for I/O operations.

IoBuf and IoBufMut store readable/writable cursor state directly in the public handle. Allocation ownership lives in a compact tagged owner reference: runtime-owned heap buffers keep a header inside their own allocation (in front of the data for low-alignment mutable buffers, at the tail for high-alignment ones and adopted vecs), pooled buffers keep their owner record in a per-slot side table owned by the size class, caller-supplied Vec<u8> values converted to immutable buffers are adopted into the native heap form when their spare capacity allows (mutable conversions copy to preserve the caller’s capacity), and caller-supplied Bytes values are held zero-copy by a small external owner. This keeps bytes::Buf and bytes::BufMut hot paths as simple pointer/length arithmetic. owner.rs documents the owner model.

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

Conversions

Every From conversion into IoBuf or IoBufs is zero-copy: the payload is never copied. Most conversions require at most one small owner allocation. A Vec<u8> that cannot host an inline owner may require two small metadata allocations: one for bytes shared ownership and one for the external owner. Conversions into IoBufMut or IoBufsMut are zero-copy where the source allocation can back a mutable handle and copy otherwise. Each mutable conversion documents which one it is, and conversions out of the handles document their cost on each impl.

Because untracked heap buffers embed their owner header in the same allocation, a power-of-two capacity request may land in the allocator’s next size bin. Pooled buffers do not pay this: their side-table record keeps the data allocation exactly the class size.

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
• BufferPool: Pool of reusable, aligned 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);

// Unique again: the mutable handle returns 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

BufferPool

A pool of reusable, aligned buffers.

BufferPoolClassConfig

Configuration for one enabled buffer pool size class.

BufferPoolConfig

Configuration for a buffer pool.

BufferPoolThreadCache

Access to the calling thread’s local BufferPool caches.

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.

Enums

PoolError

Error returned when buffer pool allocation fails.

Traits

EncodeExt

Extension trait for encoding values into pooled I/O buffers.

Functions

cache_line_size

Returns the cache line size for the current architecture.

page_size

Returns the system page size.