state_restore_gate.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/audio/buffer.hpp>
 
#include <algorithm>
#include <cstdint>
#include <atomic>
#include <mutex>
#include <thread>
 
namespace pulp::format {

template <typename Sample>
void silence_block(audio::BufferView<Sample>& out) {
    const std::size_t frames = out.num_samples();
    for (std::size_t ch = 0; ch < out.num_channels(); ++ch) {
        auto o = out.channel(ch);
        for (std::size_t n = 0; n < frames; ++n) o[n] = Sample{0};
    }
}

template <typename Sample>
void passthrough_block(audio::BufferView<Sample>& out,
                       const audio::BufferView<const Sample>& in) {
    const std::size_t channels = std::min(out.num_channels(), in.num_channels());
    const std::size_t frames = out.num_samples();
    for (std::size_t ch = 0; ch < channels; ++ch) {
        auto o = out.channel(ch);
        auto i = in.channel(ch);
        for (std::size_t n = 0; n < frames; ++n) o[n] = i[n];
    }
    for (std::size_t ch = channels; ch < out.num_channels(); ++ch) {
        auto o = out.channel(ch);
        for (std::size_t n = 0; n < frames; ++n) o[n] = Sample{0};
    }
}
 
class StateRestoreGate {
public:
    class [[nodiscard]] RenderLock {
      public:
        RenderLock(const RenderLock&) = delete;
        RenderLock& operator=(const RenderLock&) = delete;
        ~RenderLock() {
            if (!gate_)
                return;
            const std::uint32_t prev = gate_->state_.fetch_sub(1, std::memory_order_acq_rel);
            // Only a render that finishes while a restore waits pays for the
            // wake-up; an uncontended block is one atomic decrement.
            if ((prev & kRestoring) != 0)
                gate_->state_.notify_all();
        }
 
        explicit operator bool() const noexcept {
            return gate_ != nullptr;
        }
 
      private:
        friend class StateRestoreGate;
        explicit RenderLock(StateRestoreGate* gate) noexcept : gate_(gate) {}
        StateRestoreGate* gate_;
    };

    class [[nodiscard]] RestoreLock {
      public:
        RestoreLock(const RestoreLock&) = delete;
        RestoreLock& operator=(const RestoreLock&) = delete;
        ~RestoreLock() {
            gate_.state_.fetch_and(~kRestoring, std::memory_order_release);
        }
 
      private:
        friend class StateRestoreGate;
        RestoreLock(StateRestoreGate& gate, std::unique_lock<std::mutex> writer) noexcept
            : gate_(gate), writer_(std::move(writer)) {}
        StateRestoreGate& gate_;
        // Released after the flag is cleared (members destroy after the body),
        // so a second restorer can never observe a half-released gate.
        std::unique_lock<std::mutex> writer_;
    };

    RenderLock lock_for_render() noexcept {
        const std::uint32_t prev = state_.fetch_add(1, std::memory_order_acquire);
        if ((prev & kRestoring) != 0) {
            state_.fetch_sub(1, std::memory_order_relaxed);
            contended_blocks_.fetch_add(1, std::memory_order_relaxed);
            return RenderLock(nullptr);
        }
        return RenderLock(this);
    }

    RestoreLock lock_for_restore() {
        std::unique_lock<std::mutex> writer(writer_mutex_);
        std::uint32_t current = state_.fetch_or(kRestoring, std::memory_order_acq_rel) | kRestoring;
        // A render in flight usually finishes within microseconds, so spin
        // briefly; after that, sleep until a finishing render wakes us rather
        // than burning a core for the rest of a long block.
        for (int spin = 0; spin < kSpinsBeforeWait && (current & kRenderMask) != 0; ++spin) {
            std::this_thread::yield();
            current = state_.load(std::memory_order_acquire);
        }
        while ((current & kRenderMask) != 0) {
            state_.wait(current, std::memory_order_acquire);
            current = state_.load(std::memory_order_acquire);
        }
        return RestoreLock(*this, std::move(writer));
    }

    std::uint64_t contended_blocks() const noexcept {
        return contended_blocks_.load(std::memory_order_relaxed);
    }
 
  private:
    static constexpr std::uint32_t kRestoring = 0x8000'0000u;
    static constexpr std::uint32_t kRenderMask = ~kRestoring;
    static constexpr int kSpinsBeforeWait = 64;
    static_assert(std::atomic<std::uint32_t>::is_always_lock_free,
                  "the render side of the gate must be lock-free");
 
    // High bit: a restore holds (or is acquiring) the gate. Low bits: renders
    // currently inside process().
    std::atomic<std::uint32_t> state_{0};
    std::mutex writer_mutex_;
    std::atomic<std::uint64_t> contended_blocks_{0};
};
 
}  // namespace pulp::format