Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,10 @@ if(PROJECT_IS_TOP_LEVEL AND BUILD_TESTING)

if(UNIX AND NOT APPLE)
spscqueue_executable(SPSCQueueBenchmark src/SPSCQueueBenchmark.cpp)
find_library(RTE_RING_LIBRARY rte_ring)
if(RTE_RING_LIBRARY)
target_link_libraries(SPSCQueueBenchmark PRIVATE ${RTE_RING_LIBRARY})
endif()
spscqueue_executable(SPSCQueueExampleHugepages src/SPSCQueueExampleHugepages.cpp)
endif()

Expand Down
111 changes: 85 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,21 @@
# SPSCQueue.h

A single-producer single-consumer queue written in C++20. It has a fixed capacity
and supports wait-free operations.

In the benchmarks below, it is faster than both
[*boost::lockfree::spsc*](https://www.boost.org/doc/libs/1_76_0/doc/html/boost/lockfree/spsc_queue.html)
and [*folly::ProducerConsumerQueue*](https://github.com/facebook/folly/blob/master/folly/docs/ProducerConsumerQueue.md).
A single-header, wait-free single-producer single-consumer queue written in
C++20.

Why choose `SPSCQueue`:

- **Fast under real workloads**: leads all tested queues in bounded throughput
(`219.3 Mops/s`) with `86–91 ns` warm round-trip latency (faster than
`boost::lockfree::spsc_queue`, `folly::ProducerConsumerQueue`,
`moodycamel::ReaderWriterQueue`, `dro::SPSCQueue`, and `DPDK rte_ring`).
- **No artificial type or capacity restrictions**: supports
non-default-constructible and immovable types, arbitrary non-power-of-two
capacities, custom allocators (including `allocate_at_least`), and zero-copy
consumption (`front()`/`pop()`, `try_consume()`).
- **Drop-in and rigorously verified**: single header with no external
dependencies, 100% MC/DC test coverage, and bounded RC11 weak-memory
verification with GenMC.

## Example

Expand Down Expand Up @@ -247,28 +257,77 @@ verification layers:

## Benchmarks

Throughput benchmark measures throughput between 2 threads for a queue of `int`
items.

Latency benchmark measures round trip time between 2 threads communicating using
2 queues of `int` items.

Benchmark results for a AMD Ryzen 9 3900X 12-Core Processor, the 2 threads are
running on different cores on the same chiplet:

| Queue | Throughput (ops/ms) | Latency RTT (ns) |
| ---------------------------- | ------------------: | ---------------: |
| SPSCQueue | 362723 | 133 |
| boost::lockfree::spsc | 209877 | 222 |
| folly::ProducerConsumerQueue | 148818 | 147 |

## Cited by
`SPSCQueueBenchmark` interleaves all queues in a Latin-square order across
multiple trials and reports the median for four workloads using `int` items:

- **Bounded throughput** (`Mops/s`): 50M operations on a 65,536-entry queue.
This is the primary throughput metric: real queues run under backpressure
where producer and consumer repeatedly catch up, wrap around, and exchange
cache lines, rather than simply buffering millions of items uncontested.
- **Decoupled throughput** (`Mops/s`): 2M operations on a 2M-entry queue.
Measures uncontended per-operation overhead when the ring is large enough
that producer and consumer rarely stall on each other.
- **Warm latency** (`ns RTT`): 2M round trips between 2 threads via 2 queues.
Measures best-case ping-pong handoff latency with queue metadata hot in CPU
caches, isolating atomic synchronization and false-sharing overhead.
- **Cold latency** (`ns RTT`): round trips striped across 262,144 queue pairs.
Evicts queue state from CPU caches between accesses, measuring how compact
and cache-friendly the queue layout is under bursty or many-queue workloads.

To build and run the benchmark with all optional comparison queues using Nix:

```sh
nix develop --command bash -c "cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --target SPSCQueueBenchmark"
./build/SPSCQueueBenchmark 0 1
```

SPSCQueue have been cited by the following papers:
Median results on an AMD Ryzen 7 8745HS (2 threads pinned to separate physical
cores 0 and 1 sharing L3 cache):

| Queue | Decoupled (Mops/s) | Bounded (Mops/s) | Warm RTT (ns) | Cold RTT (ns) |
| --- | ---: | ---: | ---: | ---: |
| `rigtorp::SPSCQueue` | 717.3 | 219.3 | 91 | 142 |
| `rigtorp::SPSCQueue` (`try_pop`) | 683.4 | 204.2 | 86 | 161 |
| `rigtorp::SPSCQueue` (`try_consume`) | 696.8 | 200.0 | 86 | 125 |
| `boost::lockfree::spsc_queue` | 207.5 | 186.9 | 155 | 163 |
| `folly::ProducerConsumerQueue` | 226.5 | 149.0 | 136 | 146 |
| `rigtorp::MPMCQueue` | 65.7 | 61.4 | 118 | 294 |
| `moodycamel::ReaderWriterQueue` | 218.1 | 164.9 | 139 | 155 |
| `dro::SPSCQueue` | 866.4 | 172.1 | 154 | 147 |
| `atomic_queue::AtomicQueueB` (`SPSC`) | 739.5 | 204.2 | 95 | 97 |
| `atomic_queue::AtomicQueueB2` (`SPSC`) | 654.1 | 163.7 | 100 | 106 |
| `DPDK rte_ring` (`SP/SC`) | 180.0 | 133.1 | 146 | 145 |

## Citation

If you use SPSCQueue in a paper, please cite it. Include the version or commit
used in your work.

```bibtex
@misc{rigtorp_spscqueue,
author = {Erik Rigtorp},
title = {{SPSCQueue}},
howpublished = {\url{https://github.com/rigtorp/SPSCQueue}}
}
```

- Peizhao Ou and Brian Demsky. 2018. Towards understanding the costs of avoiding
out-of-thin-air results. Proc. ACM Program. Lang. 2, OOPSLA, Article 136
(October 2018), 29 pages. DOI: <https://doi.org/10.1145/3276506>
Publications that cite SPSCQueue:

- Peizhao Ou and Brian Demsky. 2018.
[Towards Understanding the Costs of Avoiding Out-of-Thin-Air Results](https://doi.org/10.1145/3276506).
OOPSLA.
- Thibaut Carpentier. 2018.
[Synchronisation de données inter-processus dans les applications audio temps réel : qu’est-ce qui débloque ?](https://hal.science/hal-01791422).
JIM, pp. 35–44.
- Jörg Christian Kirchhof. 2022.
[Model-Driven Development, Deployment, and Analysis of Internet of Things Applications](https://www.se-rwth.de/phdtheses/Diss-Kirchhof-Model-Driven-Development-Deployment-and-Analysis-of-Internet-of-Things-Applications.pdf).
Doctoral thesis.
- Clément Allain. 2025.
[Verification of fine-grained concurrent OCaml 5 algorithms using separation logic](https://iris-project.org/pdfs/2025-phd-allain.pdf).
Doctoral thesis.
- Ziye Xie et al. 2026.
[Toward Accurate and Accessible Markerless Neuronavigation](https://arxiv.org/abs/2602.07052v1).
Preprint, version 1.

## About

Expand Down
78 changes: 78 additions & 0 deletions flake.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

94 changes: 94 additions & 0 deletions flake.nix
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
{
description = "SPSCQueue benchmark environment with optional comparison queues";

inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
mpmcqueue = {
url = "github:rigtorp/MPMCQueue";
flake = false;
};
dro-spsc-queue = {
url = "github:drogalis/SPSC-Queue";
flake = false;
};
atomic-queue = {
url = "github:max0x7ba/atomic_queue";
flake = false;
};
};

outputs = {
self,
nixpkgs,
mpmcqueue,
dro-spsc-queue,
atomic-queue,
}: let
supportedSystems = ["x86_64-linux" "aarch64-linux"];
forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
in {
packages = forAllSystems (system: let
pkgs = nixpkgs.legacyPackages.${system};
benchmark = pkgs.stdenv.mkDerivation {
pname = "spscqueue-benchmark";
version = "2.0.0";
src = ./.;

hardeningDisable = ["all"];

nativeBuildInputs = [pkgs.cmake];
buildInputs = [
pkgs.boost.dev
pkgs.dpdk
pkgs.folly.dev
pkgs.readerwriterqueue
];

cmakeFlags = [
"-DCMAKE_BUILD_TYPE=Release"
"-DBUILD_TESTING=ON"
];

env.NIX_CFLAGS_COMPILE = "-isystem ${mpmcqueue}/include -isystem ${dro-spsc-queue}/include -isystem ${atomic-queue}/include";

buildFlags = ["SPSCQueueBenchmark"];

installPhase = ''
runHook preInstall
mkdir -p $out/bin
cp SPSCQueueBenchmark $out/bin/SPSCQueueBenchmark
runHook postInstall
'';
};
in {
inherit benchmark;
default = benchmark;
});

apps = forAllSystems (system: {
benchmark = {
type = "app";
program = "${self.packages.${system}.benchmark}/bin/SPSCQueueBenchmark";
};
default = self.apps.${system}.benchmark;
});

devShells = forAllSystems (system: let
pkgs = nixpkgs.legacyPackages.${system};
in {
default = pkgs.mkShell {
packages = [
pkgs.cmake
pkgs.ninja
pkgs.boost.dev
pkgs.dpdk
pkgs.folly.dev
pkgs.readerwriterqueue
];
shellHook = ''
export NIX_CFLAGS_COMPILE="''${NIX_CFLAGS_COMPILE:-} -isystem ${mpmcqueue}/include -isystem ${dro-spsc-queue}/include -isystem ${atomic-queue}/include"
'';
};
});
};
}
Loading
Loading