SpscQueue.h

Go to the documentation of this file.

// DSPark -- Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi -- MIT License
 
#pragma once
 
#include <array>
#include <atomic>
#include <cstddef>
#include <type_traits>
 
namespace dspark {
 
// Cache-line size used for false-sharing padding. Fixed per architecture on
// purpose: std::hardware_destructive_interference_size may vary with tuning
// flags (GCC documents this and warns about it), and a header-only library
// must never let the layout of the same template differ between translation
// units. 128 on AArch64 covers Apple Silicon's 128-byte lines (over-padding
// on 64-byte ARM cores is harmless); 64 everywhere else.
#if defined(__aarch64__) || defined(_M_ARM64)
    inline constexpr std::size_t kCacheLineSize = 128;
#else
    inline constexpr std::size_t kCacheLineSize = 64;
#endif
 
template <typename T, std::size_t Capacity = 32>
class SpscQueue
{
    static_assert(Capacity > 0 && (Capacity & (Capacity - 1)) == 0,
                  "SpscQueue: Capacity must be a power of two.");
    static_assert(std::is_trivially_copyable_v<T>,
                  "SpscQueue: Element type must be trivially copyable for lock-free safety.");
 
public:
    SpscQueue() = default;
 
    SpscQueue(const SpscQueue&)            = delete;
    SpscQueue& operator=(const SpscQueue&) = delete;
 
    [[nodiscard]] bool push(const T& item) noexcept
    {
        const auto write = writePos_.load(std::memory_order_relaxed);
        const auto next  = (write + 1) & kMask;
 
        // Check against cached read position first to avoid cross-core atomic load
        if (next == cachedReadPos_)
        {
            cachedReadPos_ = readPos_.load(std::memory_order_acquire);
            if (next == cachedReadPos_)
                return false; // Truly full
        }
 
        buffer_[write] = item;
        writePos_.store(next, std::memory_order_release);
        return true;
    }
 
    [[nodiscard]] bool pop(T& item) noexcept
    {
        const auto read = readPos_.load(std::memory_order_relaxed);
 
        // Check against cached write position first to avoid cross-core atomic load
        if (read == cachedWritePos_)
        {
            cachedWritePos_ = writePos_.load(std::memory_order_acquire);
            if (read == cachedWritePos_)
                return false; // Truly empty
        }
 
        item = buffer_[read];
        readPos_.store((read + 1) & kMask, std::memory_order_release);
        return true;
    }
 
    [[nodiscard]] std::size_t sizeApprox() const noexcept
    {
        const auto w = writePos_.load(std::memory_order_relaxed);
        const auto r = readPos_.load(std::memory_order_relaxed);
        return (w - r) & kMask;
    }
 
    [[nodiscard]] bool empty() const noexcept { return sizeApprox() == 0; }
 
    [[nodiscard]] static constexpr std::size_t capacity() noexcept { return Capacity - 1; }
 
private:
    static constexpr std::size_t kMask = Capacity - 1;
 
    std::array<T, Capacity> buffer_ {};
 
#ifdef _MSC_VER
#pragma warning(push)
#pragma warning(disable: 4324) // structure was padded due to alignment specifier
#endif
 
    // ========================================================================
    // Producer Cache Line
    // ========================================================================
    alignas(kCacheLineSize) std::atomic<std::size_t> writePos_ {0};
    std::size_t cachedReadPos_ {0}; // Only read/written by the producer
 
    // ========================================================================
    // Consumer Cache Line
    // ========================================================================
    alignas(kCacheLineSize) std::atomic<std::size_t> readPos_ {0};
    std::size_t cachedWritePos_ {0}; // Only read/written by the consumer
 
#ifdef _MSC_VER
#pragma warning(pop)
#endif
};
 
} // namespace dspark