triple_buffer.hpp

Go to the documentation of this file.

#pragma once

 
#include <atomic>
#include <cassert>
#include <array>
#include <cstdint>
#include <type_traits>
#include <utility>
 
namespace pulp::runtime {

template <typename T>
class TripleBuffer {
public:
    static_assert(std::atomic<std::uint8_t>::is_always_lock_free,
                  "TripleBuffer publication flags must be lock-free");
 
    TripleBuffer() = default;

    explicit TripleBuffer(const T& initial) {
        buffers_[0] = initial;
        buffers_[1] = initial;
        buffers_[2] = initial;
    }

    void write(const T& value) noexcept(std::is_nothrow_copy_assignable_v<T>) {
        write_with(
            [&value](T& back) noexcept(std::is_nothrow_copy_assignable_v<T>) { back = value; });
    }

    template <typename Fill>
    void write_with(Fill&& fill) noexcept(noexcept(std::declval<Fill>()(std::declval<T&>()))) {
        [[maybe_unused]] const RoleGuard guard(active_roles_, kWriterRole);
        std::forward<Fill>(fill)(buffers_[back_]);
        // One exchange publishes the filled buffer as the middle slot and
        // hands the previous middle slot back to the writer. Release makes the
        // fill visible to the reader's acquire; acquire orders the reader's
        // last use of the returned slot before the writer refills it.
        const auto previous = middle_.exchange(static_cast<std::uint8_t>(back_ | kDirtyBit),
                                               std::memory_order_acq_rel);
        back_ = previous & kIndexMask;
    }

    const T& read() noexcept {
        [[maybe_unused]] const RoleGuard guard(active_roles_, kReaderRole);
        if (middle_.load(std::memory_order_relaxed) & kDirtyBit) {
            const auto previous = middle_.exchange(front_, std::memory_order_acq_rel);
            front_ = previous & kIndexMask;
        }
        return buffers_[front_];
    }
 
  private:
    // middle_ holds the index of the slot between writer and reader, plus a
    // dirty bit set by the writer and cleared by the reader's swap. back_ is
    // owned by the writer thread and front_ by the reader thread; neither is
    // shared, so neither needs to be atomic.
    static constexpr std::uint8_t kDirtyBit = 0x80;
    static constexpr std::uint8_t kIndexMask = 0x03;
 
    // Debug-only overlap check for the one-writer / one-reader contract. The
    // flag byte is present in every build so the layout does not depend on
    // NDEBUG; release builds never touch it.
    static constexpr std::uint8_t kWriterRole = 0x01;
    static constexpr std::uint8_t kReaderRole = 0x02;
    struct RoleGuard {
#ifndef NDEBUG
        RoleGuard(std::atomic<std::uint8_t>& roles, std::uint8_t role) noexcept
            : roles_(roles), role_(role) {
            const auto before = roles_.fetch_or(role_, std::memory_order_acquire);
            assert((before & role_) == 0 && "TripleBuffer: two overlapping calls in the same role");
            (void)before;
        }
        ~RoleGuard() {
            roles_.fetch_and(static_cast<std::uint8_t>(~role_), std::memory_order_release);
        }
        std::atomic<std::uint8_t>& roles_;
        std::uint8_t role_;
#else
        RoleGuard(std::atomic<std::uint8_t>&, std::uint8_t) noexcept {}
#endif
    };
 
    std::array<T, 3> buffers_{};
    std::atomic<std::uint8_t> middle_{1};
    std::uint8_t back_ = 0;
    std::uint8_t front_ = 2;
    std::atomic<std::uint8_t> active_roles_{0};
};
 
} // namespace pulp::runtime