scheduler.hpp

Go to the documentation of this file.

#pragma once
 
// IScheduler — unified scheduling base.
//
// Aria has historically grown three sibling abstractions:
//
//   * `aria::async::IExecutor`       — "post(fn)"; used by coroutines /
//                                       async_command / graph executor.
//   * `aria::runtime::IDispatcher`   — "post(fn) + post_delayed + pump +
//                                       is_main_thread"; the platform
//                                       UI/main-thread dispatcher.
//   * `aria::IDelayedScheduler`      — "post_after(delay, fn)"; the tiny
//                                       timer interface used by debounce
//                                       / throttle / retry / with_timeout.
//
// Each grew its own naming, its own role, and its own capability story.
// `IScheduler` is the single inheritance root that lets every component
// in the framework reason about "what can this thing do?" through a
// stable, declarative bitmask — without breaking any existing concrete
// class hierarchy.
//
//   ┌────────────────────────────┐
//   │       IScheduler           │  caps(): SchedulerCaps  bitmask
//   │       schedule(fn)         │  pure virtual — submit a callable
//   │       schedule_after(...)  │  default: throws unsupported_capability
//   └─────────────┬──────────────┘
//                 │
//   ┌─────────────┼─────────────────────────────┐
//   │             │                             │
//   IDelayedScheduler        IExecutor                  IDispatcher
//   (Caps::Delay)            (Caps::Post + GraphSafe?   (Caps::Post |
//                              + WorkerSafe?)             Caps::Delay |
//                                                         Caps::MainThread |
//                                                         Caps::Pumpable)
//
// All three derived interfaces inherit from `IScheduler` virtually so
// that `VirtualTimeExecutor : IExecutor, IDelayedScheduler` (and any
// future multi-role implementation) collapses to a single IScheduler
// subobject without ambiguity.
//
// The contract is intentionally minimal: `schedule(fn)` is the only
// universally available operation. Anything else (delay, main-thread
// affinity, pumping, pool-style worker hosting) is a CAPABILITY that
// the implementation declares via `caps()`. Callers query the bitmask
// once and either (a) use a richer interface via `dynamic_cast`, or
// (b) gracefully degrade.
//
// USAGE FROM A COMPONENT THAT NEEDS A TIMER:
//
//   void wire_debounce(IScheduler& s, ...) {
//       if (!has_caps(s, SchedulerCaps::Delay))
//           throw std::logic_error("scheduler has no Delay capability");
//       s.schedule_after(300ms, []{ ... });   // safe — caps() said yes
//   }
//
// USAGE FROM A COMPONENT THAT REQUIRES A PUMPABLE MAIN-THREAD QUEUE:
//
//   if (!has_caps(s, SchedulerCaps::MainThread | SchedulerCaps::Pumpable))
//       throw ...;
//
// IMPORTANT: This header introduces *no* breaking change. Every
// pre-existing concrete class (`ThreadPoolExecutor`, `MainThreadExecutor`,
// `InlineExecutor`, `SimpleDispatcher`, `VirtualTimeExecutor`, …) is
// retrofitted with a `caps()` override that declares its capabilities.
// Existing call sites keep using the rich interfaces directly.
 
#include "aria/abi/export.hpp"
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <stdexcept>
#include <type_traits>
 
namespace aria {
 
// ────────────────────────────────────────────────────────────────────────
// Capability bitmask
//
// `enum class : std::uint32_t` so it can be stored as a packed atomic
// or a struct member without ABI surprises.
// ────────────────────────────────────────────────────────────────────────
enum class SchedulerCaps : std::uint32_t {
    None              = 0,

    Post              = 1u << 0,

    Delay             = 1u << 1,

    MainThread        = 1u << 2,

    Pumpable          = 1u << 3,

    GraphSafe         = 1u << 4,

    WorkerSafe        = 1u << 5,

    Autonomous        = 1u << 6,
};
 
[[nodiscard]] constexpr SchedulerCaps operator|(SchedulerCaps a, SchedulerCaps b) noexcept {
    return static_cast<SchedulerCaps>(static_cast<std::uint32_t>(a) | static_cast<std::uint32_t>(b));
}
[[nodiscard]] constexpr SchedulerCaps operator&(SchedulerCaps a, SchedulerCaps b) noexcept {
    return static_cast<SchedulerCaps>(static_cast<std::uint32_t>(a) & static_cast<std::uint32_t>(b));
}
constexpr SchedulerCaps& operator|=(SchedulerCaps& a, SchedulerCaps b) noexcept {
    a = a | b; return a;
}
constexpr SchedulerCaps& operator&=(SchedulerCaps& a, SchedulerCaps b) noexcept {
    a = a & b; return a;
}
[[nodiscard]] constexpr bool has_any(SchedulerCaps a, SchedulerCaps b) noexcept {
    return static_cast<std::uint32_t>(a & b) != 0;
}
[[nodiscard]] constexpr bool has_all(SchedulerCaps a, SchedulerCaps b) noexcept {
    return (a & b) == b;
}
 
// ────────────────────────────────────────────────────────────────────────
// Exceptions
// ────────────────────────────────────────────────────────────────────────

class unsupported_capability : public std::logic_error {
public:
    using std::logic_error::logic_error;
};
 
// ────────────────────────────────────────────────────────────────────────
// IScheduler
// ────────────────────────────────────────────────────────────────────────
class ARIA_ABI_API IScheduler {
public:
    virtual ~IScheduler() = default;

    [[nodiscard]] virtual SchedulerCaps caps() const noexcept = 0;

    virtual void schedule(std::function<void()> fn) = 0;

    virtual void schedule_after(std::chrono::milliseconds delay,
                                std::function<void()> fn) {
        (void)delay; (void)fn;
        throw unsupported_capability(
            "IScheduler::schedule_after: this scheduler does not advertise "
            "SchedulerCaps::Delay");
    }

    [[nodiscard]] virtual bool is_main_thread() const noexcept { return false; }
};
 
// ────────────────────────────────────────────────────────────────────────
// Free helpers
// ────────────────────────────────────────────────────────────────────────
 
[[nodiscard]] inline bool has_caps(const IScheduler& s, SchedulerCaps required) noexcept {
    return has_all(s.caps(), required);
}

inline void require_caps(const IScheduler& s, SchedulerCaps required,
                         const char* context = "scheduler") {
    if (!has_caps(s, required)) {
        throw unsupported_capability(std::string{context}
            + ": required SchedulerCaps not advertised by this scheduler");
    }
}
 
}  // namespace aria