C++ Ring Buffer and Circular Buffer Libraries: Boost.CircularBuffer vs rigtorp/SPSCQueue vs Folly ProducerConsumerQueue

Introduction

Ring buffers (also known as circular buffers) are one of the most fundamental data structures in systems programming. They provide fixed-size, FIFO (first-in-first-out) queue semantics with O(1) insertion and removal — making them ideal for embedded systems, audio processing, network packet buffering, and inter-thread communication. Unlike dynamic containers like std::vector or std::deque, ring buffers never allocate memory after construction, ensuring predictable latency and avoiding heap fragmentation.

In the C++ ecosystem, developers have several high-quality ring buffer implementations to choose from: the venerable Boost.CircularBuffer, the specialized rigtorp/SPSCQueue for single-producer-single-consumer scenarios, and Facebook’s Folly ProducerConsumerQueue for high-throughput multi-threaded workloads. Each takes a different approach to the same fundamental problem, trading off generality for performance in different dimensions.

This article compares these three libraries across latency, throughput, memory overhead, thread safety, and ease of use — with real benchmark code and Docker-based testing setups.

Ring Buffer Design Space

Before diving into library comparisons, it’s worth understanding the key design decisions that differentiate ring buffer implementations:

Library Comparison

Boost.CircularBuffer

boost::circular_buffer is the most feature-rich option in the C++ ecosystem. It’s part of Boost since version 1.35 and provides a complete STL-compatible container with iterators, random access, and full debug support.

Key Features:

• STL-compatible container (begin(), end(), random access via operator[])
• Configurable capacity with optional automatic overwriting
• bounded_buffer adaptor adds thread-safety via condition variables
• Header-only since Boost 1.80
• Supports both circular_buffer (fixed) and circular_buffer_space_optimized

Example: Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#include <boost/circular_buffer.hpp>
#include <iostream>

int main() {
    boost::circular_buffer<int> cb(5);  // capacity of 5

    // Fill buffer
    for (int i = 1; i <= 7; ++i) {
        cb.push_back(i);
    }
    // Buffer now contains: 3, 4, 5, 6, 7 (oldest 1, 2 overwritten)

    for (auto& x : cb) std::cout << x << " ";
    // Output: 3 4 5 6 7
    return 0;
}

Boost.CircularBuffer Space-Optimized Variant:

1
2
3
4
5
6
7
8

#include <boost/circular_buffer.hpp>

// space_optimized: only allocates when first element is added
boost::circular_buffer_space_optimized<int> cb(1000);
// No memory allocated yet — capacity is "virtual"

cb.push_back(42);
// Now memory for ~64 elements allocated (power-of-two growth)

Thread-Safe Bounded Buffer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#include <boost/circular_buffer.hpp>
#include <boost/thread.hpp>

boost::circular_buffer<int> cb(100);
boost::mutex mtx;
boost::condition_variable cv;

// Producer
void producer() {
    boost::mutex::scoped_lock lock(mtx);
    while (cb.full()) cv.wait(lock);
    cb.push_back(42);
    cv.notify_one();
}

// Consumer
void consumer() {
    boost::mutex::scoped_lock lock(mtx);
    while (cb.empty()) cv.wait(lock);
    int val = cb.front();
    cb.pop_front();
    cv.notify_one();
}

rigtorp/SPSCQueue

rigtorp/SPSCQueue is a specialized, header-only, lock-free, wait-free single-producer-single-consumer (SPSC) queue designed for minimal latency. At approximately 200 lines of code, it’s the polar opposite of Boost.CircularBuffer — minimal features, maximal performance.

Key Features:

• Wait-free for both producer and consumer
• Single header file (~200 LOC) — no dependencies
• Cache-line padding to prevent false sharing
• Bounded capacity, power-of-two sizing
• C++11 or later

Example: High-Performance SPSC Pipeline

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

#include <rigtorp/SPSCQueue.h>
#include <thread>
#include <iostream>
#include <chrono>

rigtorp::SPSCQueue<int> queue(1024);  // capacity must be power of 2

void producer() {
    for (int i = 0; i < 1'000'000; ++i) {
        while (!queue.try_push(i)) {
            // Busy-wait — ideal for low-latency scenarios
        }
    }
}

void consumer() {
    int sum = 0;
    int* val;
    for (int i = 0; i < 1'000'000; ++i) {
        while (!(val = queue.front())) {
            // Busy-wait
        }
        sum += *val;
        queue.pop();
    }
    std::cout << "Sum: " << sum << std::endl;
}

int main() {
    auto start = std::chrono::high_resolution_clock::now();

    std::thread t1(producer);
    std::thread t2(consumer);
    t1.join();
    t2.join();

    auto elapsed = std::chrono::high_resolution_clock::now() - start;
    std::cout << "Time: " 
              << std::chrono::duration_cast<std::chrono::milliseconds>(elapsed).count()
              << "ms" << std::endl;
}

Folly ProducerConsumerQueue

Facebook’s Folly library includes ProducerConsumerQueue, a high-performance, lock-free, single-producer-single-consumer queue designed for Facebook-scale infrastructure workloads. Unlike rigtorp/SPSCQueue, Folly’s implementation supports move semantics and non-trivial types.

Key Features:

• Lock-free SPSC semantics with atomic operations
• Supports move-only types (e.g., std::unique_ptr)
• Part of the larger Folly ecosystem (30K+ GitHub stars)
• Can be used with non-power-of-two capacities
• Read and write cursors on separate cache lines to prevent false sharing

Example: Working with Move-Only Types

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#include <folly/ProducerConsumerQueue.h>
#include <memory>
#include <thread>

struct Task {
    std::unique_ptr<int> data;
    Task(int val) : data(std::make_unique<int>(val)) {}
    Task(Task&&) = default;
    Task& operator=(Task&&) = default;
};

folly::ProducerConsumerQueue<Task> queue(1024);

void producer() {
    for (int i = 0; i < 1000; ++i) {
        Task t(i);
        while (!queue.write(std::move(t))) {
            // queue full — spin or yield
            std::this_thread::yield();
        }
    }
}

void consumer() {
    Task t(0);
    for (int i = 0; i < 1000; ++i) {
        while (!queue.read(t)) {
            std::this_thread::yield();
        }
        // Process t.data
    }
}

Performance Comparison

The following table summarizes the key performance characteristics based on benchmarks with 1 million int transfers between two threads on an Intel i9-13900K:

Benchmark Setup (Docker):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# docker-compose.yml for reproducible benchmarking
version: "3.8"
services:
  bench:
    image: gcc:13
    volumes:
      - ./benchmarks:/benchmarks
    working_dir: /benchmarks
    command: >
      sh -c "apt-get update && apt-get install -y cmake libboost-dev &&
             git clone https://github.com/facebook/folly.git &&
             cd folly && cmake -B build && cmake --build build &&
             cd /benchmarks && g++ -O3 -std=c++20 -pthread -I folly
             -I rigtorp/SPSCQueue bench.cpp -o bench && ./bench"

Choosing the Right Library

Use Boost.CircularBuffer When:

• You need STL compatibility (iterators, algorithms, range-based for)
• Thread safety model is flexible or multi-producer-multi-consumer
• Debug support and bounds checking matter
• You’re already using Boost in your project

Use rigtorp/SPSCQueue When:

• You need the absolute lowest latency (< 15ns per operation)
• SPSC semantics are sufficient for your use case
• Zero dependencies is a priority (single header file)
• You’re deploying to embedded or resource-constrained environments

Use Folly ProducerConsumerQueue When:

• You need to pass move-only types (smart pointers, file handles)
• You’re already using Folly in your codebase
• You need non-power-of-two queue capacities
• Facebook-scale throughput is required

Implementation Comparison: Critical Sections

The core difference between these libraries lies in how they handle the read/write cursor synchronization. Here’s a simplified comparison:

Boost.CircularBuffer (mutex-based thread safety):

1
2
3
4
5

// Thread safety is external — use mutex + condition_variable
boost::mutex mtx;
boost::condition_variable cv;
// Producer: lock → check full → push → notify
// Consumer: lock → check empty → pop → notify

rigtorp/SPSCQueue (wait-free atomics):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Pseudo-code of core algorithm
void push(T&& val) {
    auto writeIdx = writeIndex.load(std::memory_order_relaxed);
    auto nextIdx = writeIdx + 1;
    // Only producer writes to writeIdx — no compare_exchange needed
    while (nextIdx - readIndex.load(std::memory_order_acquire) > capacity_) {
        // spin — wait for consumer to catch up
    }
    slots_[writeIdx % capacity_] = std::move(val);
    writeIndex.store(nextIdx, std::memory_order_release);
}

Folly PCQ (lock-free with explicit fencing):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Uses explicit memory fences for finer control
bool write(T&& record) {
    auto currentWrite = writeCounter_.load(std::memory_order_relaxed);
    auto nextRecord = currentWrite + 1;
    if (nextRecord - readCounter_.load(std::memory_order_acquire) > size_) {
        return false;  // full — caller decides to spin or yield
    }
    records_[currentWrite % size_] = std::move(record);
    writeCounter_.store(nextRecord, std::memory_order_release);
    return true;
}

The key insight: rigtorp uses a simpler algorithm that trusts the SPSC invariant (only producer writes to writeIdx), while Folly provides more explicit control with separate read/write counters, enabling non-blocking fallback (return false instead of spinning).

Why Self-Host Your Ring Buffer Stack?

When building low-latency systems, choosing the right ring buffer library has cascading effects on overall system design. A ring buffer operating at 12ns per operation enables architectures that simply wouldn’t be viable at 120ns — think algorithmic trading systems processing market data tick-by-tick, or live audio processing pipelines where jitter above 50μs is unacceptable.

Understanding these library differences matters whether you’re building a self-hosted message broker, a custom network proxy, or an embedded telemetry collector. The right choice can mean the difference between meeting your P99 latency SLOs and spending weeks debugging mysterious tail latencies.

For more on lock-free data structures, see our comparison of lock-free concurrent data structures and our deep dive into lock-free queue libraries.

For hash table performance comparisons, check out our C++ hash container libraries guide.

FAQ

What is the difference between a ring buffer and a regular queue?

A ring buffer uses a fixed-size underlying array where the write pointer wraps around to the beginning when it reaches the end — hence “circular” or “ring.” Standard queues like std::queue (backed by std::deque) dynamically allocate memory as elements are added. Ring buffers never allocate after construction, ensuring constant-time operations with no memory allocation overhead. This makes them ideal for real-time systems, audio processing, and networking where predictable latency is critical.

When should I use a mutex-based buffer vs. a lock-free one?

Use mutex-based synchronization (like Boost’s bounded_buffer adaptor) when you need multi-producer-multi-consumer (MPMC) semantics, or when your critical section involves complex operations beyond simple push/pop. Use lock-free SPSC queues when you have a single producer and single consumer thread — the latency advantage is dramatic (12ns vs 120ns per operation). The overhead of lock-free MPMC algorithms is high enough that mutex-based approaches are often competitive.

Can I use Boost.CircularBuffer with custom allocators?

Yes. Boost.CircularBuffer accepts a custom allocator as a template parameter. This is particularly useful for shared memory scenarios where you want the buffer’s storage to be in a memory-mapped region accessible from multiple processes. Example: boost::circular_buffer<int, shm_allocator<int>> cb(1024, alloc_instance).

Why doesn’t rigtorp/SPSCQueue support move semantics?

rigtorp/SPSCQueue is designed for minimal overhead and maximum portability. It stores elements by value (using assignment, not construction) and provides access via raw pointers (front() returns T*). This design choice keeps the implementation under 200 lines and eliminates branching in the hot path. If you need move semantics for non-trivial types, use Folly ProducerConsumerQueue instead.

How do I choose the right capacity for my ring buffer?

A general rule of thumb: set capacity to at least 2× the maximum burst size you expect. For audio processing (48kHz, 256-sample frames), a buffer of 8-16 frames provides adequate headroom. For network packet processing, calculate based on the maximum byte rate and your processing time per packet. The power-of-two requirement for SPSCQueue means you may need to round up — a queue that needs 1000 slots should be sized at 1024.

Can ring buffers be used across processes (IPC)?

Yes, but with caveats. The buffer storage must be in shared memory (via shm_open + mmap on Linux, or CreateFileMapping on Windows). Lock-free algorithms using atomics work across processes only if the atomic operations use the same memory ordering semantics — std::atomic with memory_order_seq_cst is safe across processes on most platforms. Avoid libraries that use pointers internally (they won’t be valid in both processes), and prefer offset-based addressing for the buffer indices.

💰 想测试你的市场判断力？我用 Polymarket 做预测市场交易——这是全球最大的预测市场平台，从大选结果到技术监管时间线，什么都可以押注。和赌博不同，这是真正的信息市场：你懂的信息越多，胜率越高。我靠预测技术相关事件的走向已经赚了不少。用我的邀请链接注册：Polymarket.com