# d-nithinteja/swiftspsc architecture

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

- Interactive diagram: https://gitdiagram.com/d-nithinteja/swiftspsc
- Repository: https://github.com/d-nithinteja/swiftspsc

## Overview

#### Purpose and Entry Points
SwiftSPSC is a C++ lock-free single-producer/single-consumer queue library with two execution modes: reusable in-process thread communication and Linux shared-memory IPC. The public include surface is `include/swiftspsc/swiftspsc.h`; the primary queue type is `include/swiftspsc/spsc_queue.h`. CMake builds examples, benchmarks, and installation artifacts from `CMakeLists.txt`.

#### In-Process Queue Core
`include/swiftspsc/spsc_queue.h` implements `swiftspsc::SPSCQueue<T>` as a fixed-capacity, power-of-two ring buffer. One producer owns enqueue-side progress and one consumer owns dequeue-side progress; this ownership model avoids locks. The API supports nonblocking `try_*` operations and spinning `push`/`pop` operations.

#### Lock-Free Coordination and Memory Boundary
Queue correctness relies on atomic head/tail indices, acquire/release publication, and mask-based ring indexing. Producer-side cached consumer progress and consumer-side cached producer progress reduce cross-core atomic reads. Shared queue conventions and lower-level IPC primitives are centralized in `include/swiftspsc/queue_common.h`.

#### IPC Shared-Memory Pipeline
The IPC path uses named shared memory and a producer/consumer lifecycle. `examples/ipc/producer.cpp` creates or initializes the shared queue, publishes items, and signals completion. `examples/ipc/consumer.cpp` waits for readiness, drains published work, observes the done state, and reports throughput. This mode preserves batch publication behavior rather than treating each enqueue as an independent cross-process publication.

#### HFT Integration Shape
The `hft` directory demonstrates a likely market-data-to-strategy handoff built on SPSC-style communication. `hft/md_gateway.cpp` represents ingestion/gateway-side production; `hft/strategy_engine.cpp` represents downstream consumption and strategy execution; `hft/hft_types.h` defines their exchanged domain types. This isolates market-data acquisition from latency-sensitive strategy processing through a bounded queue boundary.

#### Performance Evaluation
Thread-mode benchmarks measure throughput and latency under producer/consumer execution: `benchmarks/thread_throughput.cpp` and `benchmarks/thread_latency.cpp`. `examples/thread/basic.cpp` is the minimal in-process integration entry point. Benchmark quality depends on release compilation, CPU affinity/isolation, and repeated percentile-based measurements.

#### Runtime and Delivery
The project is native C++ built with CMake (`CMakeLists.txt`) and has no web or managed runtime. IPC execution is Linux-oriented due to named shared-memory usage. The library is primarily header-based under `include/swiftspsc/`, with CMake installation exposing those headers to downstream C++ consumers.

Main entry points: [`include/swiftspsc/spsc_queue.h`](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h) (SPSCQueue<T>), [`CMakeLists.txt`](https://github.com/d-nithinteja/swiftspsc/blob/main/CMakeLists.txt) (CMake Build & Install), [`include/swiftspsc/queue_common.h`](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/queue_common.h) (Named Shared Queue), [`hft/hft_types.h`](https://github.com/d-nithinteja/swiftspsc/blob/main/hft/hft_types.h) (Market Data Types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Header Library"]
  node_public_header["Public Include Surface<br/>public header<br/>[swiftspsc.h]"]
  node_spsc_queue["SPSCQueue&lt;T&gt;<br/>lock-free ring queue<br/>[spsc_queue.h]"]
  node_queue_coordination["Atomic Ring Coordination<br/>queue internals<br/>[spsc_queue.h]"]
  node_queue_common["Shared Queue Conventions<br/>IPC primitives<br/>[queue_common.h]"]
end

subgraph group_ipc["Shared-Memory IPC"]
  node_ipc_producer["IPC Producer<br/>producer process<br/>[producer.cpp]"]
  node_shared_memory_queue[("Named Shared Queue<br/>shared-memory queue<br/>[queue_common.h]")]
  node_ipc_consumer["IPC Consumer<br/>consumer process<br/>[consumer.cpp]"]
end

subgraph group_hft["HFT Handoff"]
  node_hft_types["Market Data Types<br/>domain types<br/>[hft_types.h]"]
  node_md_gateway["Market Data Gateway<br/>producer runtime<br/>[md_gateway.cpp]"]
  node_strategy_engine["Strategy Engine<br/>consumer runtime"]
  node_hft_queue_boundary["Bounded Queue Boundary<br/>SPSC handoff<br/>[spsc_queue.h]"]
end

subgraph group_evaluation["Examples &amp; Benchmarks"]
  node_thread_example["Thread Basic Example<br/>in-process entry point<br/>[basic.cpp]"]
  node_thread_throughput["Thread Throughput<br/>benchmark"]
  node_thread_latency["Thread Latency<br/>benchmark<br/>[thread_latency.cpp]"]
end

node_cmake{{"CMake Build &amp; Install<br/>build system<br/>[CMakeLists.txt]"}}

node_cmake -->|"installs"| node_public_header
node_cmake -->|"builds"| node_thread_example
node_cmake -->|"builds"| node_thread_throughput
node_cmake -->|"builds"| node_thread_latency
node_cmake -->|"builds"| node_ipc_producer
node_cmake -->|"builds"| node_ipc_consumer
node_public_header -->|"exposes"| node_spsc_queue
node_spsc_queue -->|"implements with"| node_queue_coordination
node_spsc_queue -->|"uses conventions"| node_queue_common
node_thread_example -->|"uses"| node_spsc_queue
node_thread_throughput -->|"measures"| node_spsc_queue
node_thread_latency -->|"measures"| node_spsc_queue
node_ipc_producer -->|"creates and publishes"| node_shared_memory_queue
node_shared_memory_queue -->|"published batches and done state"| node_ipc_consumer
node_shared_memory_queue -->|"uses IPC primitives"| node_queue_common
node_md_gateway -->|"produces"| node_hft_queue_boundary
node_hft_queue_boundary -->|"consumes"| node_strategy_engine
node_hft_queue_boundary -->|"is implemented by"| node_spsc_queue
node_hft_types -->|"defines messages"| node_md_gateway
node_hft_types -->|"defines messages"| node_strategy_engine

click node_cmake "https://github.com/d-nithinteja/swiftspsc/blob/main/CMakeLists.txt"
click node_public_header "https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/swiftspsc.h"
click node_spsc_queue "https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h"
click node_queue_coordination "https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h"
click node_queue_common "https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/queue_common.h"
click node_thread_example "https://github.com/d-nithinteja/swiftspsc/blob/main/examples/thread/basic.cpp"
click node_thread_throughput "https://github.com/d-nithinteja/swiftspsc/blob/main/benchmarks/thread_throughput.cpp"
click node_thread_latency "https://github.com/d-nithinteja/swiftspsc/blob/main/benchmarks/thread_latency.cpp"
click node_ipc_producer "https://github.com/d-nithinteja/swiftspsc/blob/main/examples/ipc/producer.cpp"
click node_shared_memory_queue "https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/queue_common.h"
click node_ipc_consumer "https://github.com/d-nithinteja/swiftspsc/blob/main/examples/ipc/consumer.cpp"
click node_hft_types "https://github.com/d-nithinteja/swiftspsc/blob/main/hft/hft_types.h"
click node_md_gateway "https://github.com/d-nithinteja/swiftspsc/blob/main/hft/md_gateway.cpp"
click node_strategy_engine "https://github.com/d-nithinteja/swiftspsc/blob/main/hft/strategy_engine.cpp"
click node_hft_queue_boundary "https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h"

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_public_header,node_spsc_queue,node_queue_coordination,node_queue_common toneBlue
class node_ipc_producer,node_shared_memory_queue,node_ipc_consumer toneAmber
class node_hft_types,node_md_gateway,node_strategy_engine,node_hft_queue_boundary toneMint
class node_thread_example,node_thread_throughput,node_thread_latency toneRose
class node_cmake toneNeutral
```

## Components

### Header Library

Header-based SPSC queue implementation.

- [Public Include Surface](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/swiftspsc.h): public header · `include/swiftspsc/swiftspsc.h`
- [SPSCQueue<T>](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h): lock-free ring queue · Fixed-capacity power-of-two queue with try and spinning APIs. · `include/swiftspsc/spsc_queue.h`
- [Atomic Ring Coordination](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h): queue internals · Head/tail publication, cached progress, and mask indexing. · `include/swiftspsc/spsc_queue.h`
- [Shared Queue Conventions](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/queue_common.h): IPC primitives · Centralizes shared queue conventions and lower-level IPC support. · `include/swiftspsc/queue_common.h`

### Shared-Memory IPC

Linux producer/consumer example pipeline.

- [IPC Producer](https://github.com/d-nithinteja/swiftspsc/blob/main/examples/ipc/producer.cpp): producer process · Initializes named shared queue, publishes items, then signals completion. · `examples/ipc/producer.cpp`
- [Named Shared Queue](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/queue_common.h): shared-memory queue · Batch-published queue state shared between Linux processes. · `include/swiftspsc/queue_common.h`
- [IPC Consumer](https://github.com/d-nithinteja/swiftspsc/blob/main/examples/ipc/consumer.cpp): consumer process · Waits for readiness, drains work, observes done state, and reports throughput. · `examples/ipc/consumer.cpp`

### HFT Handoff

Market-data to strategy queue boundary.

- [Market Data Types](https://github.com/d-nithinteja/swiftspsc/blob/main/hft/hft_types.h): domain types · Types exchanged across the gateway-to-strategy boundary. · `hft/hft_types.h`
- [Market Data Gateway](https://github.com/d-nithinteja/swiftspsc/blob/main/hft/md_gateway.cpp): producer runtime · Ingests market data and produces bounded-queue messages. · `hft/md_gateway.cpp`
- [Strategy Engine](https://github.com/d-nithinteja/swiftspsc/blob/main/hft/strategy_engine.cpp): consumer runtime · Consumes market data for latency-sensitive strategy execution. · `hft/strategy_engine.cpp`
- [Bounded Queue Boundary](https://github.com/d-nithinteja/swiftspsc/blob/main/include/swiftspsc/spsc_queue.h): SPSC handoff · Isolates acquisition from strategy processing. · `include/swiftspsc/spsc_queue.h`

### Examples & Benchmarks

- [Thread Basic Example](https://github.com/d-nithinteja/swiftspsc/blob/main/examples/thread/basic.cpp): in-process entry point · `examples/thread/basic.cpp`
- [Thread Throughput](https://github.com/d-nithinteja/swiftspsc/blob/main/benchmarks/thread_throughput.cpp): benchmark · `benchmarks/thread_throughput.cpp`
- [Thread Latency](https://github.com/d-nithinteja/swiftspsc/blob/main/benchmarks/thread_latency.cpp): benchmark · Uses repeated percentile-based latency measurements. · `benchmarks/thread_latency.cpp`

### Other components

- [CMake Build & Install](https://github.com/d-nithinteja/swiftspsc/blob/main/CMakeLists.txt): build system · Builds examples and benchmarks and installs public headers. · `CMakeLists.txt`

## Connections

- CMake Build & Install → Public Include Surface: installs
- CMake Build & Install → Thread Basic Example: builds
- CMake Build & Install → Thread Throughput: builds
- CMake Build & Install → Thread Latency: builds
- CMake Build & Install → IPC Producer: builds
- CMake Build & Install → IPC Consumer: builds
- Public Include Surface → SPSCQueue<T>: exposes
- SPSCQueue<T> → Atomic Ring Coordination: implements with
- SPSCQueue<T> → Shared Queue Conventions: uses conventions
- Thread Basic Example → SPSCQueue<T>: uses
- Thread Throughput → SPSCQueue<T>: measures
- Thread Latency → SPSCQueue<T>: measures
- IPC Producer → Named Shared Queue: creates and publishes
- Named Shared Queue → IPC Consumer: published batches and done state
- Named Shared Queue → Shared Queue Conventions: uses IPC primitives
- Market Data Gateway → Bounded Queue Boundary: produces
- Bounded Queue Boundary → Strategy Engine: consumes
- Bounded Queue Boundary → SPSCQueue<T>: is implemented by
- Market Data Types → Market Data Gateway: defines messages
- Market Data Types → Strategy Engine: defines messages