Ring Buffer

app.domain.video.ring_buffer

View source code

Circular frame buffer with thread-safe O(1) lookup for video playback buffering.

See Also

• VideoDecodeWorker — fills the buffer with decoded frames
• SessionFrameAccessor — reads buffered frames for a session

Layer: Domain. Context: Defines application concepts independently of UI and infrastructure implementations.

VideoRingBuffer

High-performance circular array (ring buffer) for caching contiguous frame sequences.

ATTRIBUTE	DESCRIPTION
capacity	Fixed number of frames cached in the ring. TYPE: int

Note

Provides O(1) frame lookup through modulo hashing while tracking a contiguous [start_idx, end_idx] range. Uses a lightweight threading.Lock() for thread safety and pre-allocates storage with no dynamic resizing. Used by VideoDecodeWorker for both sequential playback buffering and hard seeks. When the buffer wraps, the oldest frame is overwritten and the start index advances.

Example

buffer = VideoRingBuffer(capacity=90) buffer.push(0, frame_0) buffer.push(1, frame_1) frame = buffer.get(0) # O(1) lookup buffer.clear() # Free memory for inactive session

PARAMETER	DESCRIPTION
capacity	Number of frame slots allocated in the ring buffer. TYPE: int DEFAULT: 90

capacity = capacity instance-attribute

__init__(capacity: int = 90)

clear() -> None

Reset buffer bounds and clear all slots (frees memory for inactive sessions).

get(idx: int) -> RGBFrame | None

Return cached frame at idx, or None if cache miss (out of bounds).

PARAMETER	DESCRIPTION
idx	Absolute frame index to look up in the buffer. TYPE: int

RETURNS	DESCRIPTION
RGBFrame | None	Cached RGB frame when idx is within the stored range; otherwise None.

push(idx: int, frame: RGBFrame) -> None

Push frame at idx (thread-safe), update bounds, handle wrapping.

PARAMETER	DESCRIPTION
idx	Frame index to store. TYPE: int
frame	Decoded RGB frame data to cache. TYPE: RGBFrame

Note

If the buffer is empty or a hard seek introduces a gap in the sequence, the start index resets to idx. The frame is stored in slot idx % capacity, the end index is updated, and wrapping advances the start index when the oldest frame is overwritten.