# rigtorp/spscqueue architecture

> Architecture diagram of the GitHub repository rigtorp/spscqueue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rigtorp/spscqueue
- Repository: https://github.com/rigtorp/spscqueue

## Overview

#### Purpose and public entry point
This is a header-only C++11 library implementing a fixed-capacity, wait-free/lock-free single-producer/single-consumer queue. Consumers include `include/rigtorp/SPSCQueue.h` directly; queue construction takes an item capacity and supports custom allocators.

#### Core queue implementation
`include/rigtorp/SPSCQueue.h` contains the entire production implementation and public API: blocking and non-blocking enqueue (`emplace`/`push`, `try_emplace`/`try_push`), inspection (`front`, `size`, `empty`), and dequeue (`pop`). The type contract permits exactly one producer thread and one consumer thread; other concurrent access is invalid.

#### Ring-buffer storage and ownership
The queue allocates a contiguous slot buffer sized for requested capacity plus one sentinel slot, allowing arbitrary non-power-of-two capacities while distinguishing full from empty. Producer-side operations construct elements into writable slots; consumer-side `front()` exposes the current element and `pop()` destroys it. `pop()` therefore requires a non-empty queue and a nothrow-destructible item type. Implementation: `include/rigtorp/SPSCQueue.h`.

#### Concurrent index protocol
Producer and consumer coordinate through head/read and tail/write indices. Each side owns updates to its respective index and reads the counterpart only as needed to determine empty/full state. Local cached remote indices let successive operations proceed without repeatedly loading the other thread’s index, reducing cache-coherency traffic. Implementation: `include/rigtorp/SPSCQueue.h`; conceptual layout: `spsc.odg`.

#### Memory-layout and performance boundary
Head and tail indices are aligned/padded to avoid false sharing. The slot storage is also padded at both ends to isolate it from adjacent allocations. These cache-layout decisions are integral to the queue’s performance model rather than optional tuning. Implementation: `include/rigtorp/SPSCQueue.h`.

#### Allocation extension point
Storage is obtained through the standard allocator interface. With C++17, the implementation can use allocator size-feedback (`allocate_at_least`), enabling callers to efficiently provide platform-specific huge-page allocators without embedding OS allocation policy in the library. The Linux huge-page usage example is `src/SPSCQueueExampleHugepages.cpp`; the core remains platform-neutral in `include/rigtorp/SPSCQueue.h`.

#### Build, validation, and executable entry points
CMake defines the project build and example/test/benchmark executables in `CMakeLists.txt`. `src/SPSCQueueExample.cpp` demonstrates producer/consumer usage; `src/SPSCQueueBenchmark.cpp` measures two-thread throughput and round-trip latency; `src/SPSCQueueTest.cpp` exercises single-thread correctness and multithreaded contention behavior. GitHub Actions runs C/C++ CI through `.github/workflows/ccpp.yml`.

Main entry points: [`include/rigtorp/SPSCQueue.h`](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h) (SPSCQueue public API), [`CMakeLists.txt`](https://github.com/rigtorp/spscqueue/blob/master/CMakeLists.txt) (CMake build), [`src/SPSCQueueExample.cpp`](https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueExample.cpp) (Producer/consumer example), [`src/SPSCQueueExampleHugepages.cpp`](https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueExampleHugepages.cpp) (Huge-page allocator example)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Header-only queue"]
  node_queue_api["SPSCQueue public API<br/>C++ header<br/>[SPSCQueue.h]"]
  node_ownership_contract["SPSC ownership contract<br/>concurrency contract<br/>[SPSCQueue.h]"]
  node_ring_storage["Sentinel ring storage<br/>storage layer<br/>[SPSCQueue.h]"]
  node_producer_ops["Producer operations<br/>queue layer<br/>[SPSCQueue.h]"]
  node_consumer_ops["Consumer operations<br/>queue layer<br/>[SPSCQueue.h]"]
  node_index_protocol["Head/tail index protocol<br/>lock-free protocol<br/>[SPSCQueue.h]"]
  node_cache_layout["Cache-isolated layout<br/>performance boundary<br/>[SPSCQueue.h]"]
  node_allocator_extension["Allocator extension<br/>allocation interface<br/>[SPSCQueue.h]"]
  node_conceptual_layout["Queue layout diagram<br/>design diagram<br/>[spsc.odg]"]
end

subgraph group_consumers["Consumers and validation"]
  node_usage_example["Producer/consumer example<br/>example executable"]
  node_hugepage_example["Huge-page allocator example<br/>example executable"]
  node_benchmark["Throughput and latency benchmark<br/>benchmark executable"]
  node_tests["Correctness and contention tests<br/>test executable<br/>[SPSCQueueTest.cpp]"]
end

subgraph group_build["Build and CI"]
  node_cmake["CMake build<br/>build definition<br/>[CMakeLists.txt]"]
  node_ci["C/C++ CI<br/>GitHub Actions workflow<br/>[ccpp.yml]"]
end

node_queue_api -->|"requires"| node_ownership_contract
node_queue_api -->|"provides"| node_producer_ops
node_queue_api -->|"provides"| node_consumer_ops
node_producer_ops -->|"constructs into"| node_ring_storage
node_consumer_ops -->|"reads and destroys"| node_ring_storage
node_producer_ops -->|"advances write side"| node_index_protocol
node_consumer_ops -->|"advances read side"| node_index_protocol
node_index_protocol -->|"coordinates slots"| node_ring_storage
node_cache_layout -->|"isolates"| node_index_protocol
node_cache_layout -->|"pads"| node_ring_storage
node_allocator_extension -->|"allocates"| node_ring_storage
node_conceptual_layout -.->|"documents"| node_index_protocol
node_usage_example -->|"uses"| node_queue_api
node_hugepage_example -->|"supplies allocator to"| node_allocator_extension
node_benchmark -->|"measures"| node_queue_api
node_tests -->|"validates"| node_queue_api
node_cmake -->|"builds"| node_usage_example
node_cmake -->|"builds"| node_hugepage_example
node_cmake -->|"builds"| node_benchmark
node_cmake -->|"builds"| node_tests
node_ci -->|"runs"| node_cmake

click node_queue_api "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_ownership_contract "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_ring_storage "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_producer_ops "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_consumer_ops "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_index_protocol "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_cache_layout "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_allocator_extension "https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h"
click node_conceptual_layout "https://github.com/rigtorp/spscqueue/blob/master/spsc.odg"
click node_usage_example "https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueExample.cpp"
click node_hugepage_example "https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueExampleHugepages.cpp"
click node_benchmark "https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueBenchmark.cpp"
click node_tests "https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueTest.cpp"
click node_cmake "https://github.com/rigtorp/spscqueue/blob/master/CMakeLists.txt"
click node_ci "https://github.com/rigtorp/spscqueue/blob/master/.github/workflows/ccpp.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_queue_api,node_ownership_contract,node_ring_storage,node_producer_ops,node_consumer_ops,node_index_protocol,node_cache_layout,node_allocator_extension,node_conceptual_layout toneBlue
class node_usage_example,node_hugepage_example,node_benchmark,node_tests toneAmber
class node_cmake,node_ci toneMint
```

## Components

### Header-only queue

Public API and concurrency-critical implementation.

- [SPSCQueue public API](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): C++ header · Fixed-capacity queue construction, enqueue, inspection, and dequeue API. · `include/rigtorp/SPSCQueue.h`
- [SPSC ownership contract](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): concurrency contract · Exactly one producer and one consumer may access a queue concurrently. · `include/rigtorp/SPSCQueue.h`
- [Sentinel ring storage](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): storage layer · Contiguous capacity-plus-one slot buffer supports arbitrary capacities. · `include/rigtorp/SPSCQueue.h`
- [Producer operations](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): queue layer · Constructs items through blocking and non-blocking push operations. · `include/rigtorp/SPSCQueue.h`
- [Consumer operations](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): queue layer · Exposes front items and destroys them on pop. · `include/rigtorp/SPSCQueue.h`
- [Head/tail index protocol](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): lock-free protocol · Owned indices and cached remote indices determine full and empty state. · `include/rigtorp/SPSCQueue.h`
- [Cache-isolated layout](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): performance boundary · Padded aligned indices and storage prevent false sharing. · `include/rigtorp/SPSCQueue.h`
- [Allocator extension](https://github.com/rigtorp/spscqueue/blob/master/include/rigtorp/SPSCQueue.h): allocation interface · Uses standard allocators and C++17 allocation size feedback when available. · `include/rigtorp/SPSCQueue.h`
- [Queue layout diagram](https://github.com/rigtorp/spscqueue/blob/master/spsc.odg): design diagram · `spsc.odg`

### Consumers and validation

- [Producer/consumer example](https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueExample.cpp): example executable · `src/SPSCQueueExample.cpp`
- [Huge-page allocator example](https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueExampleHugepages.cpp): example executable · Demonstrates Linux huge-page allocation without platform policy in the core. · `src/SPSCQueueExampleHugepages.cpp`
- [Throughput and latency benchmark](https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueBenchmark.cpp): benchmark executable · Measures two-thread throughput and round-trip latency. · `src/SPSCQueueBenchmark.cpp`
- [Correctness and contention tests](https://github.com/rigtorp/spscqueue/blob/master/src/SPSCQueueTest.cpp): test executable · Covers single-thread correctness and multithreaded contention. · `src/SPSCQueueTest.cpp`

### Build and CI

- [CMake build](https://github.com/rigtorp/spscqueue/blob/master/CMakeLists.txt): build definition · Defines example, benchmark, and test executables. · `CMakeLists.txt`
- [C/C++ CI](https://github.com/rigtorp/spscqueue/blob/master/.github/workflows/ccpp.yml): GitHub Actions workflow · `.github/workflows/ccpp.yml`

## Connections

- SPSCQueue public API → SPSC ownership contract: requires
- SPSCQueue public API → Producer operations: provides
- SPSCQueue public API → Consumer operations: provides
- Producer operations → Sentinel ring storage: constructs into
- Consumer operations → Sentinel ring storage: reads and destroys
- Producer operations → Head/tail index protocol: advances write side
- Consumer operations → Head/tail index protocol: advances read side
- Head/tail index protocol → Sentinel ring storage: coordinates slots
- Cache-isolated layout → Head/tail index protocol: isolates
- Cache-isolated layout → Sentinel ring storage: pads
- Allocator extension → Sentinel ring storage: allocates
- Queue layout diagram → Head/tail index protocol: documents
- Producer/consumer example → SPSCQueue public API: uses
- Huge-page allocator example → Allocator extension: supplies allocator to
- Throughput and latency benchmark → SPSCQueue public API: measures
- Correctness and contention tests → SPSCQueue public API: validates
- CMake build → Producer/consumer example: builds
- CMake build → Huge-page allocator example: builds
- CMake build → Throughput and latency benchmark: builds
- CMake build → Correctness and contention tests: builds
- C/C++ CI → CMake build: runs