cancel.hpp

Go to the documentation of this file.

#pragma once
 
// Cooperative cancellation.
//
//   CancelSource  - move-only owner. Calls `cancel()`, and cancels on destruction.
//   CancelToken   - copyable observer handed to the work being cancelled.
//   CancelRegistration - RAII handle for a callback registered on a token.
//
// A default-constructed CancelToken is never cancelled, so APIs can take a
// `const CancelToken& = {}` parameter and treat "no token" as "cannot be
// cancelled" without a null check.
//
// Threading: every member is safe to call from any thread. `is_cancelled()` is
// a single acquire load of a lock-free atomic. It never locks and never
// allocates, so it may be polled from the audio thread. Everything else
// (`wait_for_cancellation`, `register_callback`, `cancel`) takes a mutex and
// may allocate, and must stay off the audio thread.
 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
 
namespace pulp::runtime {
 
class CancelToken;
class CancelSource;
 
namespace detail {
struct CancelStateBase {
    std::atomic<bool> cancelled{false};
    virtual ~CancelStateBase() = default;
};
} // namespace detail

using CancelCallback = std::function<void()>;

class CancelRegistration {
  public:
    CancelRegistration() noexcept = default;
    ~CancelRegistration();
 
    CancelRegistration(const CancelRegistration&) = delete;
    CancelRegistration& operator=(const CancelRegistration&) = delete;
    CancelRegistration(CancelRegistration&& other) noexcept;
    CancelRegistration& operator=(CancelRegistration&& other) noexcept;

    [[nodiscard]] explicit operator bool() const noexcept {
        return id_ != 0;
    }

    void reset() noexcept;
 
  private:
    friend class CancelToken;
    CancelRegistration(std::shared_ptr<detail::CancelStateBase> state, std::uint64_t id) noexcept
        : state_(std::move(state)), id_(id) {}
 
    std::shared_ptr<detail::CancelStateBase> state_;
    std::uint64_t id_ = 0;
};
 
class CancelToken {
  public:
    CancelToken() noexcept = default;

    [[nodiscard]] bool is_cancelled() const noexcept {
        return state_ && state_->cancelled.load(std::memory_order_acquire);
    }

    [[nodiscard]] bool can_be_cancelled() const noexcept {
        return state_ != nullptr;
    }

    bool wait_for_cancellation(std::chrono::nanoseconds timeout) const;

    [[nodiscard]] CancelRegistration register_callback(CancelCallback fn) const;

    [[nodiscard]] bool shares(const CancelToken& other) const noexcept {
        return state_ == other.state_;
    }
 
  protected:
    using State = detail::CancelStateBase;
    explicit CancelToken(std::shared_ptr<State> state) noexcept : state_(std::move(state)) {}

    static bool request_cancel(const std::shared_ptr<State>& state) noexcept;
    static std::shared_ptr<State> make_state();
 
    std::shared_ptr<State> state_;
 
    friend class CancelSource;
};

class CancelSource {
  public:
    CancelSource();
    ~CancelSource();
 
    CancelSource(const CancelSource&) = delete;
    CancelSource& operator=(const CancelSource&) = delete;
    CancelSource(CancelSource&& other) noexcept = default;
    CancelSource& operator=(CancelSource&& other) noexcept;

    [[nodiscard]] CancelToken token() const noexcept {
        return token_;
    }

    bool cancel() noexcept;
 
    [[nodiscard]] bool is_cancelled() const noexcept {
        return token_.is_cancelled();
    }
 
  private:
    CancelToken token_;
};

class CancellationToken : public CancelToken {
  public:
    CancellationToken();
 
    void cancel() noexcept {
        request_cancel(state_);
    }
};
 
} // namespace pulp::runtime