class

Filament::Capture::RingBuffer(T)

Inherits Reference < Object

A generic circular ring buffer that supports concurrent single-producer and single-consumer access via atomic index operations.

buffer = Filament::Capture::RingBuffer(Int32).new(1024)
buffer.push(42)
value = buffer.pop # => 42

When the buffer is full, push overwrites the oldest item and increments the drop counter. When empty, pop returns nil.

Constructors

new(capacity : Int32)

Creates a new ring buffer with the specified capacity. The capacity must be at least 1 (and ideally a power of 2 for performance, but we don't enforce that since modulo works fine for our scale).

Source

Instance methods

capacity

The fixed capacity of this buffer. Cannot be changed after creation.

Source

clear

Removes all items from the buffer and resets the statistics. Not safe to call while producer/consumer are active.

Source

each

Iterates over all items currently in the buffer without removing them. This is a snapshot operation - items pushed during iteration may or may not be seen, and items popped during iteration may cause inconsistencies. Best used when the producer is paused.

NOTE: This copies the items to avoid races. For large buffers with large items, this can be expensive.

Source

empty?

Is the buffer empty?

Source

full?

Is the buffer at capacity?

Source

pop

Pops the oldest item from the buffer. Returns nil if the buffer is empty.

This method is designed to be called from a single consumer fiber. It never blocks.

Source

pop_batch(max : Int32) : Array(T)

Tries to pop up to max items at once, returning them in an array. This is more efficient than calling pop in a loop because we only pay the atomic read overhead once for the count check.

Source

push(item : T) : Nil

Pushes an item into the buffer. If the buffer is full, the oldest item is silently overwritten and counted as a drop.

This method is designed to be called from a single producer fiber. It never blocks, which is critical for the capture path.

Source

size

Current number of items in the buffer.

Source

stats

Returns a snapshot of the current buffer statistics. This is a point-in-time view; values may change immediately after reading.

Source

to_a

Returns all items currently in the buffer as an array, without removing them. Same caveats as each about concurrency.

Source

to_s(io : IO) : Nil

Returns a human-readable summary of the buffer state.

Source

utilization

How full is the buffer, as a percentage?

Source