Struct RingBuffer

Owning bounded FIFO for queues whose capacity is chosen at runtime.

struct RingBuffer(T);

RingBuffer is useful when a caller needs a fixed maximum queue size but cannot know that size at compile time. It acquires one backing allocation, preserves FIFO order across physical wraparound, and exposes the logical sequence as at most two contiguous borrowed segments for bulk processing.

The backing storage is acquired once and retained across push, pop, and clear operations. Exactly length slots contain live T objects. The container never overwrites old elements when full.

Copy construction is disabled because backing storage is uniquely owned. Whole-buffer move transfers ownership in O(1) without relocating live elements.

Constructors

NameDescription
this (capacity) Acquires backing storage for the requested number of elements.
this (rhs) Unique owning storage is never copied implicitly.
this (rhs) Transfers backing-storage ownership in O(1).

Methods

NameDescription
back () Mutable logical back element.
capacity () Returns the maximum number of live elements.
clear () Destroys all live elements while retaining the backing allocation.
empty () Reports whether the buffer contains no live elements.
firstSegment () Returns the first contiguous physical segment in logical FIFO order.
front () Mutable logical front element.
full () Reports whether no additional element can be inserted.
length () Returns the number of live elements.
opAssign (rhs) Identity assignment remains unavailable in the first owning API.
opIndex (logicalIndex) Returns a mutable reference by logical FIFO index.
popFront () Destroys and removes the logical front element.
secondSegment () Returns the wrapped continuation after firstSegment.
tryPushBack (value) Appends one element without overwriting existing contents.

Parameters

NameDescription
T element type

Init

.init is a valid empty zero-capacity buffer.

Allocation

Positive construction may acquire one backing allocation. Steady-state push, pop, indexing, segment access, and clear do not reacquire storage.

Thread Safety

Instances are not synchronized. External synchronization is required for concurrent mutation or mutation concurrent with reads.

Example

Reuse one runtime-sized FIFO allocation across normal queue operations. 

auto queue = RingBuffer!int(4);

// Filling and draining the queue never changes its established capacity.
assert(queue.tryPushBack(10));
assert(queue.tryPushBack(20));
queue.popFront();
assert(queue.front == 20);
assert(queue.capacity == 4);

// Clear removes live values but keeps the backing allocation for reuse.
queue.clear();
assert(queue.empty);
assert(queue.capacity == 4);