alive_token.hpp

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <condition_variable>
#include <cstddef>
#include <memory>
#include <mutex>
#include <utility>
 
namespace pulp::runtime {

class AliveToken {
    struct State {
        std::atomic<bool> alive{true};
        std::atomic<bool> retired{false};
        std::mutex mutex;
        std::condition_variable quiesced;
        std::size_t active_leases = 0;
 
        // Keep Handle source compatibility for existing callback sites that
        // only need an atomic liveness read or fire-and-forget invalidation.
        // Owner teardown that must wait for in-flight users calls
        // AliveToken::retire(), which also drains active leases.
        bool load(std::memory_order order = std::memory_order_seq_cst) const noexcept {
            return alive.load(order);
        }
 
        void store(bool value, std::memory_order order = std::memory_order_seq_cst) noexcept {
            if (!value) {
                std::lock_guard lock(mutex);
                retired.store(true, std::memory_order_release);
                alive.store(false, order);
                return;
            }
            // A captured Handle can outlive its AliveToken. Never allow a
            // stale callback to resurrect a retired owner; reset() publishes
            // a fresh State when resurrection is actually intended.
            std::lock_guard lock(mutex);
            if (retired.load(std::memory_order_acquire))
                return;
            alive.store(true, order);
        }
    };
 
  public:
    using Handle = std::shared_ptr<State>;

    class Lease {
      public:
        Lease() noexcept = default;
        Lease(const Lease&) = delete;
        Lease& operator=(const Lease&) = delete;
 
        Lease(Lease&& other) noexcept : state_(std::move(other.state_)) {}
 
        Lease& operator=(Lease&& other) noexcept {
            if (this != &other) {
                release();
                state_ = std::move(other.state_);
            }
            return *this;
        }
 
        ~Lease() {
            release();
        }
 
        explicit operator bool() const noexcept {
            return static_cast<bool>(state_);
        }

        void reset() noexcept {
            release();
        }
 
      private:
        friend class AliveToken;
 
        explicit Lease(Handle state) noexcept : state_(std::move(state)) {}
 
        void release() noexcept {
            if (!state_)
                return;
            auto state = std::move(state_);
            {
                std::lock_guard lock(state->mutex);
                // A Lease can only be created by try_acquire(), which bumps
                // this counter while holding the same mutex.
                --state->active_leases;
            }
            state->quiesced.notify_all();
        }
 
        Handle state_;
    };
 
    AliveToken() : state_(std::make_shared<State>()) {}
    ~AliveToken() {
        retire();
    }
 
    AliveToken(const AliveToken&) = delete;
    AliveToken& operator=(const AliveToken&) = delete;
    AliveToken(AliveToken&&) = delete;
    AliveToken& operator=(AliveToken&&) = delete;
 
    Handle capture() const noexcept {
        return state_;
    }

    void retire() noexcept {
        const auto state = state_;
        if (!state)
            return;
 
        std::unique_lock lock(state->mutex);
        state->retired.store(true, std::memory_order_release);
        state->alive.store(false, std::memory_order_release);
        state->quiesced.wait(lock, [&state] { return state->active_leases == 0; });
    }
 
    void reset() {
        retire();
        state_ = std::make_shared<State>();
    }
 
    static bool is_alive(const Handle& handle) noexcept {
        return handle && handle->alive.load(std::memory_order_acquire);
    }
 
    // Preserve the read-only compatibility surface for older callback owners
    // that still use an independent shared atomic sentinel. These sentinels do
    // not participate in AliveToken lease admission or retirement; callers
    // that dereference owner-backed state must use Handle plus try_acquire().
    static bool is_alive(const std::shared_ptr<std::atomic<bool>>& handle) noexcept {
        return handle && handle->load(std::memory_order_acquire);
    }

    static Lease try_acquire(const Handle& handle) noexcept {
        if (!handle)
            return {};
        std::lock_guard lock(handle->mutex);
        if (handle->retired.load(std::memory_order_acquire) ||
            !handle->alive.load(std::memory_order_acquire))
            return {};
        ++handle->active_leases;
        return Lease(handle);
    }
 
  private:
    Handle state_;
};
 
} // namespace pulp::runtime