{
    "slug": "circular_buffer",
    "term": "Circular Buffer / Ring Buffer",
    "category": "data_structures",
    "difficulty": "intermediate",
    "short": "A fixed-size array treated as circular — the write pointer wraps around when it reaches the end, overwriting the oldest data. Used for logs, audio streaming, and producer-consumer queues.",
    "long": "A circular buffer has a head (read) and tail (write) pointer. Write: place at tail, advance tail % capacity. Read: take from head, advance head % capacity. Full: tail + 1 == head. Empty: head == tail. O(1) read and write. Fixed memory — no allocation after creation. Overwrite mode: when full, advance head (discard oldest) without blocking. Lock-free single-producer/single-consumer implementations exist using atomic operations. Used in: kernel ring buffers, audio/video streaming, network packet queues, and rolling log windows.",
    "aliases": [
        "ring buffer",
        "circular queue",
        "FIFO buffer"
    ],
    "tags": [
        "data-structures",
        "performance",
        "concurrency"
    ],
    "misconception": "A circular buffer is just a queue — a standard queue grows unboundedly; a circular buffer has fixed memory and either blocks or overwrites on overflow — the fixed memory is the defining property.",
    "why_it_matters": "A logging system that uses a circular buffer keeps the last N log lines in memory with O(1) write — no allocation, no GC pressure, and a fixed memory footprint regardless of how many events are logged.",
    "common_mistakes": [
        "Not handling the full condition — writing to a full buffer silently overwrites unread data.",
        "Using modulo on non-power-of-2 sizes in tight loops — use bitwise AND with power-of-2 size for speed.",
        "Not making the buffer size a power of 2 — % operation can be replaced with & (size-1).",
        "Shared circular buffer without synchronisation — concurrent read/write requires locks or atomic operations."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "queue_data_structure",
        "lock_free_programming",
        "backpressure"
    ],
    "prerequisites": [
        "array_data_structure",
        "big_o_notation",
        "data_structures"
    ],
    "refs": [
        "https://en.wikipedia.org/wiki/Circular_buffer"
    ],
    "bad_code": "// Dynamic array as log buffer — unbounded memory:\n$logs = [];\nwhile (true) {\n    $logs[] = readEvent(); // Grows forever — OOM after enough events\n}",
    "good_code": "// Circular buffer — fixed memory, O(1) operations:\nclass CircularBuffer {\n    private array $buffer;\n    private int $head = 0;\n    private int $tail = 0;\n    private int $size = 0;\n\n    public function __construct(private int $capacity) {\n        $this->buffer = array_fill(0, $capacity, null);\n    }\n\n    public function write(mixed $item): void {\n        $this->buffer[$this->tail] = $item;\n        $this->tail = ($this->tail + 1) % $this->capacity;\n        if ($this->size < $this->capacity) $this->size++;\n        else $this->head = ($this->head + 1) % $this->capacity; // Overwrite oldest\n    }\n\n    public function read(): mixed {\n        if ($this->size === 0) return null;\n        $item = $this->buffer[$this->head];\n        $this->head = ($this->head + 1) % $this->capacity;\n        $this->size--;\n        return $item;\n    }\n}",
    "quick_fix": "Use a circular buffer (ring buffer) when you need a fixed-size queue where old data is overwritten — PHP's SplFixedArray or a simple array with modulo indexing",
    "severity": "low",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/circular_buffer",
        "html_url": "https://codeclaritylab.com/glossary/circular_buffer",
        "json_url": "https://codeclaritylab.com/glossary/circular_buffer.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Circular Buffer / Ring Buffer](https://codeclaritylab.com/glossary/circular_buffer) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/circular_buffer"
            }
        }
    }
}