coroutine.h

Go to the documentation of this file.

// Copyright (c) 2026 Tinverse LLC. All rights reserved.
// SPDX-License-Identifier: LicenseRef-Tinverse-Commercial
 
 
#pragma once
 
#include <array>
#include <concepts>
#include <coroutine>
#include <cstddef>
#include <cstdint>
#include <tuple>
#include <type_traits>
#include <utility>
 
#include "tsm/ticks.h"
 
namespace tsm {
 
class task_context;
 
class task
{
  public:
    struct promise_type;
    using handle_type = std::coroutine_handle<promise_type>;
 
    task() = default;
    explicit task(handle_type handle) noexcept
      : handle_(handle)
    {
    }
 
    task(task const&) = delete;
    task& operator=(task const&) = delete;
 
    task(task&& other) noexcept
      : handle_(other.handle_)
    {
        other.handle_ = {};
    }
 
    task& operator=(task&& other) noexcept
    {
        if (this != &other) {
            destroy();
            handle_ = other.handle_;
            other.handle_ = {};
        }
        return *this;
    }
 
    ~task()
    {
        destroy();
    }
 
    [[nodiscard]] explicit operator bool() const noexcept
    {
        return handle_ != nullptr;
    }
 
    [[nodiscard]] bool done() const noexcept
    {
        return handle_ == nullptr || handle_.done();
    }
 
    [[nodiscard]] handle_type handle() const noexcept
    {
        return handle_;
    }
 
    [[nodiscard]] bool resume();
 
  private:
    void destroy() noexcept
    {
        if (handle_ != nullptr) {
            handle_.destroy();
            handle_ = {};
        }
    }
 
    handle_type handle_{};
};
 
template<std::size_t Bytes>
class static_coroutine_arena
{
  public:
    static_assert(Bytes > 0U,
                  "tsm: static_coroutine_arena requires non-zero storage");
 
    [[nodiscard]] void* allocate(std::size_t bytes,
                                 std::size_t alignment) noexcept
    {
        const std::size_t aligned = align_up(used_, alignment);
        if (aligned > Bytes || bytes > Bytes - aligned) {
            return nullptr;
        }
        used_ = aligned + bytes;
        return storage_.data() + aligned;
    }
 
    [[nodiscard]] std::size_t used() const noexcept
    {
        return used_;
    }
    [[nodiscard]] std::size_t capacity() const noexcept
    {
        return Bytes;
    }
 
  private:
    static constexpr std::size_t align_up(std::size_t value,
                                          std::size_t alignment) noexcept
    {
        return (value + alignment - 1U) & ~(alignment - 1U);
    }
 
    alignas(std::max_align_t) std::array<unsigned char, Bytes> storage_{};
    std::size_t used_{};
};
 
enum class task_wait_kind : unsigned char
{
    ready,
    running,
    sleeping,
    predicate,
    completed,
    failed
};
 
enum class task_status : unsigned char
{
    not_started,
    ready,
    running,
    waiting,
    completed,
    failed
};
 
enum class task_failure_reason : unsigned char
{
    none,
    allocation_failed,
    frame_too_large,
    wait_queue_full,
    timer_queue_full,
    cancelled,
    unhandled_exception
};
 
enum class spawn_result : unsigned char
{
    started,
    no_slot,
    frame_too_large,
    allocation_failed,
    invalid_entry
};
 
class task_context
{
  public:
    using predicate_fn = bool (*)(void const*) noexcept;
    using wake_fn = void (*)(void*, std::size_t) noexcept;
    using sleep_fn = bool (*)(void*, std::size_t, tsm::tick_rep) noexcept;
    using cancel_sleep_fn = void (*)(void*, std::size_t) noexcept;
 
    task_context() = default;
 
    task_context(static_coroutine_arena<1U>*,
                 std::size_t,
                 std::size_t,
                 std::size_t) = delete;
 
    template<std::size_t Bytes>
    void bind(static_coroutine_arena<Bytes>& arena,
              std::size_t task_id,
              std::size_t instance_id,
              std::size_t frame_limit,
              void* scheduler,
              wake_fn wake,
              sleep_fn sleep,
              cancel_sleep_fn cancel_sleep) noexcept
    {
        // Bind is separate from coroutine construction so the scheduler can
        // prepare every slot before any task frame asks for storage.
        allocate_ = [](void* object,
                       std::size_t bytes,
                       std::size_t alignment) noexcept -> void* {
            return static_cast<static_coroutine_arena<Bytes>*>(object)
              ->allocate(bytes, alignment);
        };
        arena_ = &arena;
        task_id_ = task_id;
        instance_id_ = instance_id;
        frame_limit_ = frame_limit;
        scheduler_ = scheduler;
        wake_ = wake;
        sleep_ = sleep;
        cancel_sleep_ = cancel_sleep;
        status_ = task_status::not_started;
    }
 
    [[nodiscard]] void* allocate_frame(std::size_t bytes,
                                       std::size_t alignment) noexcept
    {
        // Coroutine allocation is part of task admission. A frame that exceeds
        // its declared budget fails the task.
        if (bytes > frame_limit_) {
            mark_failed(task_failure_reason::frame_too_large);
            return nullptr;
        }
        if (allocate_ == nullptr) {
            mark_failed(task_failure_reason::allocation_failed);
            return nullptr;
        }
        void* storage = allocate_(arena_, bytes, alignment);
        if (storage == nullptr) {
            mark_failed(task_failure_reason::allocation_failed);
        }
        return storage;
    }
 
    [[nodiscard]] std::size_t task_id() const noexcept
    {
        return task_id_;
    }
    [[nodiscard]] std::size_t instance_id() const noexcept
    {
        return instance_id_;
    }
    [[nodiscard]] tsm::tick_rep now() const noexcept
    {
        return now_;
    }
    [[nodiscard]] task_wait_kind wait_kind() const noexcept
    {
        return wait_kind_;
    }
    [[nodiscard]] task_status status() const noexcept
    {
        return status_;
    }
    [[nodiscard]] task_failure_reason failure_reason() const noexcept
    {
        return failure_reason_;
    }
    [[nodiscard]] std::uint32_t generation() const noexcept
    {
        return generation_;
    }
 
    void set_now(tsm::tick_rep now) noexcept
    {
        now_ = now;
    }
 
    void mark_ready() noexcept
    {
        if (status_ == task_status::completed ||
            status_ == task_status::failed) {
            return;
        }
        // A ready task is queued at most once. This keeps repeated signal/timer
        // wakeups from consuming ready-queue capacity before the task resumes.
        wait_kind_ = task_wait_kind::ready;
        status_ = task_status::ready;
        failure_reason_ = task_failure_reason::none;
        predicate_ = nullptr;
        predicate_object_ = nullptr;
        request_wake();
    }
 
    void prepare_start() noexcept
    {
        cancel_sleep();
        ++generation_;
        wait_kind_ = task_wait_kind::ready;
        status_ = task_status::not_started;
        failure_reason_ = task_failure_reason::none;
        predicate_ = nullptr;
        predicate_object_ = nullptr;
        queued_ = false;
    }
 
    void mark_running() noexcept
    {
        if (status_ != task_status::completed &&
            status_ != task_status::failed) {
            wait_kind_ = task_wait_kind::running;
            status_ = task_status::running;
            queued_ = false;
        }
    }
 
    void sleep_for(tsm::tick_rep ticks) noexcept
    {
        if (ticks == 0U) {
            mark_ready();
            return;
        }
        wait_kind_ = task_wait_kind::sleeping;
        status_ = task_status::waiting;
        if (sleep_ == nullptr || !sleep_(scheduler_, task_id_, ticks)) {
            mark_failed(task_failure_reason::timer_queue_full);
        }
    }
 
    void cancel_sleep() noexcept
    {
        if (cancel_sleep_ != nullptr && scheduler_ != nullptr) {
            cancel_sleep_(scheduler_, task_id_);
        }
    }
 
    template<typename Object, typename Predicate>
    void wait_until(Object const& object, Predicate predicate) noexcept
    {
        predicate_object_ = &object;
        predicate_ = predicate;
        wait_kind_ = task_wait_kind::predicate;
        status_ = task_status::waiting;
    }
 
    [[nodiscard]] bool ready_to_resume() const noexcept
    {
        switch (wait_kind_) {
            case task_wait_kind::ready:
                return true;
            case task_wait_kind::running:
                return false;
            case task_wait_kind::sleeping:
                return false;
            case task_wait_kind::predicate:
                return predicate_ != nullptr && predicate_(predicate_object_);
            case task_wait_kind::completed:
            case task_wait_kind::failed:
                return false;
        }
        return false;
    }
 
    [[nodiscard]] bool predicate_ready() const noexcept
    {
        return wait_kind_ == task_wait_kind::predicate &&
               predicate_ != nullptr && predicate_(predicate_object_);
    }
 
    void mark_completed() noexcept
    {
        wait_kind_ = task_wait_kind::completed;
        status_ = task_status::completed;
        queued_ = false;
    }
    void mark_failed(task_failure_reason reason =
                       task_failure_reason::unhandled_exception) noexcept
    {
        wait_kind_ = task_wait_kind::failed;
        status_ = task_status::failed;
        failure_reason_ = reason;
        predicate_ = nullptr;
        predicate_object_ = nullptr;
        queued_ = false;
    }
 
    void cancel() noexcept
    {
        cancel_sleep();
        mark_failed(task_failure_reason::cancelled);
    }
 
    void request_wake() noexcept
    {
        if (queued_ || wake_ == nullptr || scheduler_ == nullptr) {
            return;
        }
        queued_ = true;
        wake_(scheduler_, task_id_);
    }
 
    void clear_queued() noexcept
    {
        queued_ = false;
    }
 
  private:
    using allocate_fn = void* (*)(void*, std::size_t, std::size_t) noexcept;
 
    void* arena_{};
    void* scheduler_{};
    allocate_fn allocate_{};
    wake_fn wake_{};
    sleep_fn sleep_{};
    cancel_sleep_fn cancel_sleep_{};
    predicate_fn predicate_{};
    void const* predicate_object_{};
    std::size_t task_id_{};
    std::size_t instance_id_{};
    std::size_t frame_limit_{};
    tsm::tick_rep now_{};
    std::uint32_t generation_{};
    task_wait_kind wait_kind_{ task_wait_kind::ready };
    task_status status_{ task_status::not_started };
    task_failure_reason failure_reason_{ task_failure_reason::none };
    bool queued_{};
};
 
namespace runtime::detail {
 
inline task_context*
find_task_context() noexcept
{
    return nullptr;
}
 
template<typename First, typename... Rest>
task_context*
find_task_context(First& first, Rest&... rest) noexcept
{
    if constexpr (std::is_same_v<std::remove_cvref_t<First>, task_context>) {
        return &first;
    } else {
        return find_task_context(rest...);
    }
}
 
} // namespace runtime::detail
 
struct task::promise_type
{
    promise_type() = default;
 
    template<typename First, typename... Args>
    explicit promise_type(First& first, Args&... args) noexcept
      : context_(runtime::detail::find_task_context(first, args...))
    {
    }
 
    static task get_return_object_on_allocation_failure() noexcept
    {
        return task{};
    }
 
    static void* operator new(std::size_t) = delete;
 
    template<typename... Args>
    static void* operator new(std::size_t bytes, Args&... args) noexcept
    {
        // The task_context parameter is the allocator capability. If an entry
        // function is called without it, coroutine frame creation is rejected.
        task_context* task_ctx = runtime::detail::find_task_context(args...);
        if (task_ctx == nullptr) {
            return nullptr;
        }
        return task_ctx->allocate_frame(bytes, alignof(std::max_align_t));
    }
 
    static void operator delete(void*) noexcept {}
    static void operator delete(void*, std::size_t) noexcept {}
 
    template<typename... Args>
    static void operator delete(void*, Args&...) noexcept
    {
    }
 
    template<typename... Args>
    static void operator delete(void*, std::size_t, Args&...) noexcept
    {
    }
 
    [[nodiscard]] task get_return_object() noexcept
    {
        return task{ task::handle_type::from_promise(*this) };
    }
 
    [[nodiscard]] std::suspend_always initial_suspend() noexcept
    {
        return {};
    }
 
    struct final_awaitable
    {
        [[nodiscard]] bool await_ready() const noexcept
        {
            return false;
        }
        void await_suspend(task::handle_type handle) const noexcept
        {
            if (handle.promise().context_ != nullptr) {
                handle.promise().context_->mark_completed();
            }
        }
        void await_resume() const noexcept {}
    };
 
    [[nodiscard]] final_awaitable final_suspend() noexcept
    {
        return {};
    }
    void return_void() noexcept {}
    void unhandled_exception() noexcept
    {
        if (context_ != nullptr) {
            context_->mark_failed(task_failure_reason::unhandled_exception);
        }
    }
 
    [[nodiscard]] task_context& context() noexcept
    {
        return *context_;
    }
 
  private:
    task_context* context_{};
};
 
inline bool
task::resume()
{
    if (handle_ == nullptr || handle_.done()) {
        return false;
    }
    auto& context = handle_.promise().context();
    if (!context.ready_to_resume()) {
        return false;
    }
    context.mark_running();
    handle_.resume();
    return true;
}
 
struct yield_awaitable
{
    [[nodiscard]] bool await_ready() const noexcept
    {
        return false;
    }
    void await_suspend(task::handle_type handle) const noexcept
    {
        handle.promise().context().mark_ready();
    }
    void await_resume() const noexcept {}
};
 
[[nodiscard]] inline yield_awaitable
yield() noexcept
{
    return {};
}
 
struct sleep_ticks_awaitable
{
    tsm::tick_rep ticks{};
 
    [[nodiscard]] bool await_ready() const noexcept
    {
        return ticks == 0U;
    }
    void await_suspend(task::handle_type handle) const noexcept
    {
        handle.promise().context().sleep_for(ticks);
    }
    void await_cancel(task_context& context) const noexcept
    {
        context.cancel_sleep();
    }
    void await_resume() const noexcept {}
};
 
[[nodiscard]] inline sleep_ticks_awaitable
sleep_ticks(tsm::tick_rep ticks) noexcept
{
    return sleep_ticks_awaitable{ ticks };
}
 
[[nodiscard]] inline sleep_ticks_awaitable
sleep_ticks(tick_count ticks) noexcept
{
    return sleep_ticks_awaitable{ ticks.count() };
}
 
[[nodiscard]] inline sleep_ticks_awaitable
after_ticks(tsm::tick_rep ticks) noexcept
{
    return sleep_ticks(ticks);
}
 
[[nodiscard]] inline sleep_ticks_awaitable
after_ticks(tick_count ticks) noexcept
{
    return sleep_ticks(ticks);
}
 
class periodic_ticks
{
  public:
    explicit constexpr periodic_ticks(tsm::tick_rep period) noexcept
      : period_(period)
    {
    }
 
    explicit constexpr periodic_ticks(tick_count period) noexcept
      : period_(period.count())
    {
    }
 
    [[nodiscard]] sleep_ticks_awaitable operator co_await() const noexcept
    {
        return sleep_ticks(period_);
    }
 
    [[nodiscard]] tsm::tick_rep period() const noexcept
    {
        return period_;
    }
 
  private:
    tsm::tick_rep period_{};
};
 
using every_ticks = periodic_ticks;
 
struct timeout_ticks_awaitable
{
    tsm::tick_rep ticks{};
 
    [[nodiscard]] bool await_ready() const noexcept
    {
        return ticks == 0U;
    }
    void await_suspend(task::handle_type handle) const noexcept
    {
        handle.promise().context().sleep_for(ticks);
    }
    void await_cancel(task_context& context) const noexcept
    {
        context.cancel_sleep();
    }
    void await_resume() const noexcept {}
};
 
[[nodiscard]] inline timeout_ticks_awaitable
timeout_ticks(tsm::tick_rep ticks) noexcept
{
    return timeout_ticks_awaitable{ ticks };
}
 
[[nodiscard]] inline timeout_ticks_awaitable
timeout_ticks(tick_count ticks) noexcept
{
    return timeout_ticks_awaitable{ ticks.count() };
}
 
namespace runtime::detail {
 
template<typename Awaitable>
concept basic_awaitable = requires(Awaitable awaitable, task::handle_type h)
{
    {
        awaitable.await_ready()
        } -> std::convertible_to<bool>;
    awaitable.await_suspend(h);
    awaitable.await_resume();
};
 
template<typename T>
struct is_timeout_ticks : std::false_type
{
};
 
template<>
struct is_timeout_ticks<tsm::timeout_ticks_awaitable> : std::true_type
{
};
 
template<typename Awaitable>
void
cancel_awaitable(Awaitable& awaitable, task_context& context) noexcept
{
    if constexpr (requires { awaitable.await_cancel(context); }) {
        awaitable.await_cancel(context);
    }
}
 
} // namespace runtime::detail
 
struct select_result
{
    std::size_t index{};
};
 
template<runtime::detail::basic_awaitable... Awaitables>
class select_awaitable
{
  public:
    explicit select_awaitable(Awaitables... awaitables)
      : awaitables_(std::move(awaitables)...)
    {
    }
 
    [[nodiscard]] bool await_ready() noexcept
    {
        return ready_any(std::make_index_sequence<sizeof...(Awaitables)>{});
    }
 
    void await_suspend(task::handle_type handle) noexcept
    {
        context_ = &handle.promise().context();
        suspend_all(handle, std::make_index_sequence<sizeof...(Awaitables)>{});
    }
 
    [[nodiscard]] select_result await_resume() noexcept
    {
        static_cast<void>(
          ready_any(std::make_index_sequence<sizeof...(Awaitables)>{}));
        select_timeout_if_due(
          std::make_index_sequence<sizeof...(Awaitables)>{});
        cancel_unselected(std::make_index_sequence<sizeof...(Awaitables)>{});
        return select_result{ selected_ };
    }
 
  private:
    template<std::size_t... I>
    [[nodiscard]] bool ready_any(std::index_sequence<I...>) noexcept
    {
        bool ready{};
        ((ready = ready || ready_one<I>()), ...);
        return ready;
    }
 
    template<std::size_t I>
    [[nodiscard]] bool ready_one() noexcept
    {
        if (selected_ != npos) {
            return false;
        }
        if (std::get<I>(awaitables_).await_ready()) {
            selected_ = I;
            return true;
        }
        return false;
    }
 
    template<std::size_t... I>
    void suspend_all(task::handle_type handle,
                     std::index_sequence<I...>) noexcept
    {
        (suspend_one<I>(handle), ...);
    }
 
    template<std::size_t I>
    void suspend_one(task::handle_type handle) noexcept
    {
        if (selected_ == I || std::get<I>(awaitables_).await_ready()) {
            selected_ = I;
            return;
        }
        std::get<I>(awaitables_).await_suspend(handle);
    }
 
    template<std::size_t... I>
    void select_timeout_if_due(std::index_sequence<I...>) noexcept
    {
        if (selected_ != npos) {
            return;
        }
        ((select_timeout_index<I>()), ...);
    }
 
    template<std::size_t I>
    void select_timeout_index() noexcept
    {
        if constexpr (runtime::detail::is_timeout_ticks<
                        std::tuple_element_t<I, std::tuple<Awaitables...>>>::
                        value) {
            if (selected_ == npos) {
                selected_ = I;
            }
        }
    }
 
    template<std::size_t... I>
    void cancel_unselected(std::index_sequence<I...>) noexcept
    {
        if (context_ == nullptr || selected_ == npos) {
            return;
        }
        (cancel_one<I>(), ...);
    }
 
    template<std::size_t I>
    void cancel_one() noexcept
    {
        if (I != selected_) {
            runtime::detail::cancel_awaitable(std::get<I>(awaitables_),
                                              *context_);
        }
    }
 
    static constexpr std::size_t npos = static_cast<std::size_t>(-1);
 
    std::tuple<Awaitables...> awaitables_;
    task_context* context_{};
    std::size_t selected_{ npos };
};
 
template<typename... Awaitables>
[[nodiscard]] auto
select(Awaitables&&... awaitables)
{
    static_assert(sizeof...(Awaitables) > 0U,
                  "tsm: select requires at least one awaitable");
    return select_awaitable<std::decay_t<Awaitables>...>{
        std::forward<Awaitables>(awaitables)...
    };
}
 
template<typename Awaitable>
[[nodiscard]] auto
with_timeout(Awaitable&& awaitable, tsm::tick_rep ticks)
{
    return select(std::forward<Awaitable>(awaitable), timeout_ticks(ticks));
}
 
template<typename Awaitable>
[[nodiscard]] auto
with_timeout(Awaitable&& awaitable, tick_count ticks)
{
    return select(std::forward<Awaitable>(awaitable),
                  timeout_ticks(ticks.count()));
}
 
template<typename Runtime, typename Event>
class send_event_awaitable
{
  public:
    send_event_awaitable(Runtime& runtime, Event&& event)
      : runtime_(&runtime)
      , event_(std::forward<Event>(event))
    {
    }
 
    [[nodiscard]] bool await_ready() const noexcept
    {
        return false;
    }
 
    [[nodiscard]] bool await_suspend(task::handle_type)
    {
        accepted_ = runtime_->send_event(std::move(event_));
        return false;
    }
 
    bool await_resume() const noexcept
    {
        return accepted_;
    }
 
  private:
    Runtime* runtime_{};
    std::decay_t<Event> event_;
    bool accepted_{};
};
 
template<typename Runtime, typename Event>
class checked_send_event_awaitable
{
  public:
    checked_send_event_awaitable(Runtime& runtime, Event&& event)
      : runtime_(&runtime)
      , event_(std::forward<Event>(event))
    {
    }
 
    [[nodiscard]] bool await_ready() const noexcept
    {
        return false;
    }
 
    [[nodiscard]] bool await_suspend(task::handle_type)
    {
        accepted_ = runtime_->send_event(std::move(event_));
        return false;
    }
 
    [[nodiscard]] bool await_resume() const noexcept
    {
        return accepted_;
    }
 
  private:
    Runtime* runtime_{};
    std::decay_t<Event> event_;
    bool accepted_{};
};
 
template<typename Runtime, typename Event>
[[nodiscard]] auto
send_event(Runtime& runtime, Event&& event)
{
    return send_event_awaitable<Runtime, Event>{ runtime,
                                                 std::forward<Event>(event) };
}
 
template<typename Event, typename Runtime, typename... Args>
[[nodiscard]] auto
send(Runtime& runtime, Args&&... args)
{
    return send_event(runtime, Event{ std::forward<Args>(args)... });
}
 
template<typename Runtime, typename Event>
[[nodiscard]] auto
try_send_event(Runtime& runtime, Event&& event)
{
    return checked_send_event_awaitable<Runtime, Event>{
        runtime,
        std::forward<Event>(event),
    };
}
 
template<typename Event, typename Runtime, typename... Args>
[[nodiscard]] auto
try_send(Runtime& runtime, Args&&... args)
{
    return try_send_event(runtime, Event{ std::forward<Args>(args)... });
}
 
template<typename State, typename Machine>
class until_active_awaitable
{
  public:
    explicit until_active_awaitable(Machine& machine)
      : machine_(&machine)
    {
    }
 
    [[nodiscard]] bool await_ready() const noexcept
    {
        return machine_->template active<State>();
    }
 
    void await_suspend(task::handle_type handle) const noexcept
    {
        handle.promise().context().wait_until(
          *machine_, [](void const* object) noexcept {
              return static_cast<Machine const*>(object)
                ->template active<State>();
          });
    }
 
    void await_resume() const noexcept {}
 
  private:
    Machine* machine_{};
};
 
template<typename State, typename Machine>
[[nodiscard]] auto
until_active(Machine& machine) noexcept
{
    return until_active_awaitable<State, Machine>{ machine };
}
 
template<std::size_t Count>
struct instances
{
    static constexpr std::size_t value = Count;
};
 
template<std::size_t Bytes>
struct frame_bytes
{
    static constexpr std::size_t value = Bytes;
};
 
template<std::uint8_t Priority>
struct task_priority
{
    static constexpr std::uint8_t value = Priority;
};
 
template<std::size_t Count, typename FrameBytes>
struct dynamic_task_slots
{
    static constexpr std::size_t count = Count;
    static constexpr std::size_t frame_bytes = FrameBytes::value;
 
    static_assert(count > 0U,
                  "tsm: dynamic_task_slots requires at least one slot");
    static_assert(frame_bytes > 0U,
                  "tsm: dynamic_task_slots requires non-zero frame storage");
};
 
template<auto... Entries>
struct task_group
{
    static constexpr std::size_t size = sizeof...(Entries);
};
 
namespace runtime::detail {
 
consteval std::size_t
selected_instances()
{
    return 1U;
}
 
template<std::size_t Count, typename... Rest>
consteval std::size_t
selected_instances(tsm::instances<Count>, Rest...)
{
    return Count;
}
 
template<typename First, typename... Rest>
consteval std::size_t
selected_instances(First, Rest... rest)
{
    return selected_instances(rest...);
}
 
consteval std::size_t
selected_frame_bytes()
{
    return 0U;
}
 
template<std::size_t Bytes, typename... Rest>
consteval std::size_t
selected_frame_bytes(tsm::frame_bytes<Bytes>, Rest...)
{
    return Bytes;
}
 
template<typename First, typename... Rest>
consteval std::size_t
selected_frame_bytes(First, Rest... rest)
{
    return selected_frame_bytes(rest...);
}
 
consteval std::uint8_t
selected_priority()
{
    return 0U;
}
 
template<std::uint8_t Priority, typename... Rest>
consteval std::uint8_t
selected_priority(tsm::task_priority<Priority>, Rest...)
{
    return Priority;
}
 
template<typename First, typename... Rest>
consteval std::uint8_t
selected_priority(First, Rest... rest)
{
    return selected_priority(rest...);
}
 
} // namespace runtime::detail
 
template<auto Entry, typename... Options>
struct task_def
{
    static constexpr auto entry = Entry;
    static constexpr std::size_t instances =
      runtime::detail::selected_instances(Options{}...);
    static constexpr std::size_t frame_bytes =
      runtime::detail::selected_frame_bytes(Options{}...);
    static constexpr std::uint8_t priority =
      runtime::detail::selected_priority(Options{}...);
 
    static_assert(instances > 0U,
                  "tsm: task_def requires at least one instance");
    static_assert(frame_bytes > 0U,
                  "tsm: task_def requires non-zero frame storage");
};
 
template<typename... TaskDefinitions>
struct tasks
{
    static constexpr std::size_t size = sizeof...(TaskDefinitions);
};
 
namespace runtime {
 
namespace detail {
 
template<typename Definition, typename = void>
struct task_list_of
{
    using type = tsm::tasks<>;
};
 
template<typename Definition>
struct task_list_of<Definition, std::void_t<typename Definition::tasks>>
{
    using type = typename Definition::tasks;
};
 
template<typename Runtime, typename = void>
struct runtime_task_list_of
{
    using type = tsm::tasks<>;
};
 
template<typename Runtime>
struct runtime_task_list_of<Runtime, std::void_t<typename Runtime::definition>>
{
    using type = typename task_list_of<typename Runtime::definition>::type;
};
 
template<typename TaskList>
struct task_list_traits;
 
template<typename Definition>
concept declared_task_definition = requires
{
    Definition::entry;
    Definition::instances;
    Definition::frame_bytes;
};
 
template<typename Definition>
concept dynamic_task_definition = requires
{
    Definition::count;
    Definition::frame_bytes;
};
 
template<auto Left, auto Right>
concept same_task_entry = std::same_as<std::remove_cvref_t<decltype(Left)>,
                                       std::remove_cvref_t<decltype(Right)>>;
 
template<typename T>
struct task_entry_count
{
    static constexpr std::size_t value = 0U;
};
 
template<auto Entry, typename... Options>
struct task_entry_count<tsm::task_def<Entry, Options...>>
{
    static constexpr std::size_t value =
      tsm::task_def<Entry, Options...>::instances;
};
 
template<typename T>
struct task_dynamic_count
{
    static constexpr std::size_t value = 0U;
};
 
template<std::size_t Count, typename FrameBytes>
struct task_dynamic_count<tsm::dynamic_task_slots<Count, FrameBytes>>
{
    static constexpr std::size_t value = Count;
};
 
template<typename T>
struct task_frame_total
{
    static constexpr std::size_t value = 0U;
};
 
template<auto Entry, typename... Options>
struct task_frame_total<tsm::task_def<Entry, Options...>>
{
    static constexpr std::size_t value =
      tsm::task_def<Entry, Options...>::instances *
      tsm::task_def<Entry, Options...>::frame_bytes;
};
 
template<std::size_t Count, typename FrameBytes>
struct task_frame_total<tsm::dynamic_task_slots<Count, FrameBytes>>
{
    static constexpr std::size_t value = Count * FrameBytes::value;
};
 
template<typename... TaskDefinitions>
struct task_list_traits<tsm::tasks<TaskDefinitions...>>
{
    static constexpr std::size_t task_count =
      (0U + ... +
       (task_entry_count<TaskDefinitions>::value +
        task_dynamic_count<TaskDefinitions>::value));
    static constexpr std::size_t arena_alignment_padding =
      task_count * (alignof(std::max_align_t) - 1U);
    static constexpr std::size_t declared_task_count =
      (0U + ... + task_entry_count<TaskDefinitions>::value);
    static constexpr std::size_t dynamic_task_count =
      (0U + ... + task_dynamic_count<TaskDefinitions>::value);
    static constexpr std::size_t arena_bytes =
      (0U + ... + task_frame_total<TaskDefinitions>::value) +
      arena_alignment_padding;
};
 
template<typename Runtime>
struct task_resources
{
    using task_list = typename runtime_task_list_of<Runtime>::type;
    using traits = task_list_traits<task_list>;
 
    static constexpr std::size_t task_count = traits::task_count;
    static constexpr std::size_t declared_task_count =
      traits::declared_task_count;
    static constexpr std::size_t dynamic_task_count =
      traits::dynamic_task_count;
    static constexpr std::size_t arena_bytes = traits::arena_bytes;
    static constexpr std::size_t timer_slots = traits::task_count;
    static constexpr bool uses_heap = false;
};
 
template<std::size_t Capacity>
class timer_queue
{
  public:
    [[nodiscard]] bool schedule(std::size_t task_id,
                                tsm::tick_rep wake_tick,
                                std::uint32_t sequence) noexcept
    {
        if (size_ >= Capacity) {
            return false;
        }
        timers_[size_++] = timer_record{ task_id, wake_tick, sequence };
        return true;
    }
 
    template<typename Wake>
    std::size_t wake_due(tsm::tick_rep now, Wake wake) noexcept
    {
        // Capacity is small and static, so selection is intentionally linear.
        // Sequence numbers keep equal-deadline wakeups deterministic.
        std::size_t woken{};
        for (;;) {
            std::size_t selected = Capacity;
            for (std::size_t i = 0; i < size_; ++i) {
                if (timers_[i].wake_tick > now) {
                    continue;
                }
                if (selected == Capacity ||
                    before(timers_[i], timers_[selected])) {
                    selected = i;
                }
            }
            if (selected == Capacity) {
                return woken;
            }
            const auto record = timers_[selected];
            timers_[selected] = timers_[size_ - 1U];
            --size_;
            wake(record.task_id);
            ++woken;
        }
    }
 
    [[nodiscard]] std::size_t size() const noexcept
    {
        return size_;
    }
 
    void cancel(std::size_t task_id) noexcept
    {
        for (std::size_t i = 0; i < size_; ++i) {
            if (timers_[i].task_id != task_id) {
                continue;
            }
            timers_[i] = timers_[size_ - 1U];
            --size_;
            return;
        }
    }
 
  private:
    struct timer_record
    {
        std::size_t task_id{};
        tsm::tick_rep wake_tick{};
        std::uint32_t sequence{};
    };
 
    static constexpr bool before(timer_record const& lhs,
                                 timer_record const& rhs) noexcept
    {
        return lhs.wake_tick < rhs.wake_tick ||
               (lhs.wake_tick == rhs.wake_tick && lhs.sequence < rhs.sequence);
    }
 
    std::array<timer_record, Capacity> timers_{};
    std::size_t size_{};
};
 
template<typename Runtime, typename TaskList, bool PriorityAware = false>
class coroutine_scheduler;
 
template<typename Runtime, bool PriorityAware>
class coroutine_scheduler<Runtime, tsm::tasks<>, PriorityAware>
{
  public:
    explicit constexpr coroutine_scheduler(Runtime&) {}
 
    [[nodiscard]] bool step()
    {
        return false;
    }
    std::size_t run_ready()
    {
        return 0;
    }
    std::size_t tick(tsm::tick_rep)
    {
        return 0;
    }
    std::size_t tick(tsm::tick_count)
    {
        return 0;
    }
    std::size_t poll_waiting()
    {
        return 0;
    }
};
 
template<typename Runtime, bool PriorityAware, typename... TaskDefinitions>
class coroutine_scheduler<Runtime,
                          tsm::tasks<TaskDefinitions...>,
                          PriorityAware>
{
  public:
    using task_list = tsm::tasks<TaskDefinitions...>;
    static constexpr std::size_t task_count =
      task_list_traits<task_list>::task_count;
    static constexpr std::size_t arena_bytes =
      task_list_traits<task_list>::arena_bytes;
    static constexpr std::size_t declared_task_count =
      task_list_traits<task_list>::declared_task_count;
    static constexpr std::size_t dynamic_task_count =
      task_list_traits<task_list>::dynamic_task_count;
 
    explicit coroutine_scheduler(Runtime& runtime)
      : runtime_(&runtime)
    {
        // Construction binds every task slot to the shared arena and starts the
        // statically declared task set. Dynamic slots remain idle until
        // spawn().
        bind_all<TaskDefinitions...>();
        start_all();
    }
 
    coroutine_scheduler(coroutine_scheduler const&) = delete;
    coroutine_scheduler& operator=(coroutine_scheduler const&) = delete;
 
    [[nodiscard]] bool step()
    {
        // The default ready queue is FIFO. Priority-aware schedulers select the
        // highest priority from the same bounded queue and keep FIFO order for
        // tasks with equal priority.
        std::size_t task_id{};
        while (pop_ready(task_id)) {
            auto& context = contexts_[task_id];
            if (context.status() != task_status::ready) {
                context.clear_queued();
                continue;
            }
            context.clear_queued();
            return tasks_[task_id].resume();
        }
        return false;
    }
 
    std::size_t run_ready()
    {
        std::size_t resumed{};
        while (step()) {
            ++resumed;
        }
        return resumed;
    }
 
    std::size_t tick(tsm::tick_rep elapsed_ticks = 1U)
    {
        // Time enters this layer only as integer ticks. Platform clocks convert
        // to ticks before calling here, keeping task semantics target-neutral.
        now_ += elapsed_ticks;
        for (auto& context : contexts_) {
            context.set_now(now_);
        }
        static_cast<void>(timers_.wake_due(now_, [this](std::size_t task_id) {
            contexts_[task_id].mark_ready();
        }));
        return run_ready();
    }
 
    std::size_t tick(tsm::tick_count elapsed_ticks)
    {
        return tick(elapsed_ticks.count());
    }
 
    std::size_t poll_waiting()
    {
        // Predicate waits are evaluated cooperatively after HSM/runtime work.
        // They do not install callbacks into the observed object.
        std::size_t ready{};
        for (auto& context : contexts_) {
            if (context.predicate_ready()) {
                context.mark_ready();
                ++ready;
            }
        }
        return ready;
    }
 
    void enqueue(std::size_t task_id) noexcept
    {
        if (ready_size_ >= ready_queue_.size()) {
            contexts_[task_id].mark_failed(
              task_failure_reason::wait_queue_full);
            return;
        }
        ready_queue_[ready_push_] = task_id;
        ready_push_ = next_ready(ready_push_);
        ++ready_size_;
    }
 
    void start_all()
    {
        start_all_declared<TaskDefinitions...>();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] spawn_result start()
    {
        std::size_t base{};
        return start_entry<Entry, Instance, TaskDefinitions...>(base);
    }
 
    template<auto Entry, typename... Args>
    [[nodiscard]] spawn_result spawn(Args&&... args)
    {
        // Dynamic tasks occupy the slots after all declared task instances.
        // Completed slots can be reused because their coroutine handle has been
        // destroyed by assignment before the new entry is installed.
        for (std::size_t task_id = declared_task_count; task_id < task_count;
             ++task_id) {
            if (contexts_[task_id].status() != task_status::not_started &&
                contexts_[task_id].status() != task_status::completed &&
                contexts_[task_id].status() != task_status::failed) {
                continue;
            }
            static_assert(
              std::is_invocable_r_v<tsm::task,
                                    decltype(Entry),
                                    tsm::task_context&,
                                    Runtime&,
                                    std::size_t,
                                    Args...>,
              "tsm: spawned task must return tsm::task and accept "
              "(tsm::task_context&, Runtime&, std::size_t, args...)");
            contexts_[task_id].prepare_start();
            tasks_[task_id] = Entry(contexts_[task_id],
                                    *runtime_,
                                    task_id - declared_task_count,
                                    std::forward<Args>(args)...);
            if (!tasks_[task_id]) {
                return spawn_failure(contexts_[task_id]);
            }
            contexts_[task_id].mark_ready();
            return spawn_result::started;
        }
        return dynamic_task_count == 0U ? spawn_result::invalid_entry
                                        : spawn_result::no_slot;
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] task_status status() const
    {
        std::size_t base{};
        std::size_t task_id{};
        if (!find_entry<Entry, Instance, TaskDefinitions...>(base, task_id)) {
            return task_status::failed;
        }
        return contexts_[task_id].status();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] task_failure_reason failure_reason() const
    {
        std::size_t base{};
        std::size_t task_id{};
        if (!find_entry<Entry, Instance, TaskDefinitions...>(base, task_id)) {
            return task_failure_reason::unhandled_exception;
        }
        return contexts_[task_id].failure_reason();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] bool cancel() noexcept
    {
        std::size_t base{};
        std::size_t task_id{};
        if (!find_entry<Entry, Instance, TaskDefinitions...>(base, task_id)) {
            return false;
        }
        contexts_[task_id].cancel();
        return true;
    }
 
    void cancel_all() noexcept
    {
        for (auto& context : contexts_) {
            context.cancel();
        }
    }
 
  private:
    static constexpr spawn_result spawn_failure(
      task_context const& context) noexcept
    {
        return context.failure_reason() == task_failure_reason::frame_too_large
                 ? spawn_result::frame_too_large
                 : spawn_result::allocation_failed;
    }
 
    static constexpr std::size_t next_ready(std::size_t index) noexcept
    {
        return (index + 1U) % task_count;
    }
 
    [[nodiscard]] bool pop_ready(std::size_t& task_id) noexcept
    {
        if (ready_size_ == 0U) {
            return false;
        }
        if constexpr (PriorityAware) {
            return pop_highest_priority(task_id);
        }
        task_id = ready_queue_[ready_pop_];
        ready_pop_ = next_ready(ready_pop_);
        --ready_size_;
        return true;
    }
 
    [[nodiscard]] bool pop_highest_priority(std::size_t& task_id) noexcept
    {
        std::size_t selected_offset{};
        std::size_t selected_task = ready_queue_[ready_pop_];
        auto selected_task_priority = priorities_[selected_task];
        for (std::size_t offset = 1U; offset < ready_size_; ++offset) {
            const auto candidate = ready_queue_[ready_index(offset)];
            const auto candidate_priority = priorities_[candidate];
            if (candidate_priority > selected_task_priority) {
                selected_offset = offset;
                selected_task = candidate;
                selected_task_priority = candidate_priority;
            }
        }
 
        task_id = selected_task;
        for (std::size_t offset = selected_offset; offset + 1U < ready_size_;
             ++offset) {
            ready_queue_[ready_index(offset)] =
              ready_queue_[ready_index(offset + 1U)];
        }
        ready_push_ = ready_index(ready_size_ - 1U);
        --ready_size_;
        return true;
    }
 
    [[nodiscard]] std::size_t ready_index(std::size_t offset) const noexcept
    {
        return (ready_pop_ + offset) % task_count;
    }
 
    static void wake_task(void* scheduler, std::size_t task_id) noexcept
    {
        static_cast<coroutine_scheduler*>(scheduler)->enqueue(task_id);
    }
 
    static bool sleep_task(void* scheduler,
                           std::size_t task_id,
                           tsm::tick_rep ticks) noexcept
    {
        auto* self = static_cast<coroutine_scheduler*>(scheduler);
        return self->timers_.schedule(
          task_id, self->now_ + ticks, self->timer_sequence_++);
    }
 
    static void cancel_sleep_task(void* scheduler, std::size_t task_id) noexcept
    {
        static_cast<coroutine_scheduler*>(scheduler)->timers_.cancel(task_id);
    }
 
    template<typename... Definitions>
    void bind_all()
    {
        std::size_t index{};
        (bind_definition<Definitions>(index), ...);
    }
 
    template<typename Definition>
    void bind_definition(std::size_t& index)
    {
        // The task list can mix declared entries and dynamic slot blocks. Both
        // produce concrete task_context objects with stable numeric IDs.
        if constexpr (declared_task_definition<Definition>) {
            bind_task_definition<Definition>(index);
        } else if constexpr (dynamic_task_definition<Definition>) {
            bind_dynamic_slots<Definition>(index);
        }
    }
 
    template<typename Definition>
    void bind_task_definition(std::size_t& index)
    {
        for (std::size_t instance = 0; instance < Definition::instances;
             ++instance) {
            priorities_[index] = Definition::priority;
            contexts_[index].bind(arena_,
                                  index,
                                  instance,
                                  Definition::frame_bytes,
                                  this,
                                  wake_task,
                                  sleep_task,
                                  cancel_sleep_task);
            ++index;
        }
    }
 
    template<typename Definition>
    void bind_dynamic_slots(std::size_t& index)
    {
        for (std::size_t instance = 0; instance < Definition::count;
             ++instance) {
            contexts_[index].bind(arena_,
                                  index,
                                  instance,
                                  Definition::frame_bytes,
                                  this,
                                  wake_task,
                                  sleep_task,
                                  cancel_sleep_task);
            ++index;
        }
    }
 
    template<typename Definition>
    [[nodiscard]] spawn_result start_definition_instance(std::size_t task_id,
                                                         std::size_t instance)
    {
        if (contexts_[task_id].status() != task_status::not_started &&
            contexts_[task_id].status() != task_status::failed) {
            return spawn_result::started;
        }
        static_assert(std::is_invocable_r_v<tsm::task,
                                            decltype(Definition::entry),
                                            tsm::task_context&,
                                            Runtime&,
                                            std::size_t>,
                      "tsm: task entry must return tsm::task and accept "
                      "(tsm::task_context&, Runtime&, std::size_t)");
        contexts_[task_id].prepare_start();
        tasks_[task_id] =
          Definition::entry(contexts_[task_id], *runtime_, instance);
        if (!tasks_[task_id]) {
            return spawn_failure(contexts_[task_id]);
        }
        contexts_[task_id].mark_ready();
        return spawn_result::started;
    }
 
    template<typename... Definitions>
    void start_all_declared()
    {
        std::size_t base{};
        (start_all_for_definition<Definitions>(base), ...);
    }
 
    template<typename Definition>
    void start_all_for_definition(std::size_t& base)
    {
        if constexpr (declared_task_definition<Definition>) {
            for (std::size_t instance = 0; instance < Definition::instances;
                 ++instance) {
                static_cast<void>(start_definition_instance<Definition>(
                  base + instance, instance));
            }
            base += Definition::instances;
        } else if constexpr (dynamic_task_definition<Definition>) {
            base += Definition::count;
        }
    }
 
    template<auto Entry,
             std::size_t Instance,
             typename Definition,
             typename... Rest>
    [[nodiscard]] spawn_result start_entry(std::size_t& base)
    {
        if constexpr (declared_task_definition<Definition> &&
                      same_task_entry<Definition::entry, Entry>) {
            if constexpr (Instance < Definition::instances) {
                return start_definition_instance<Definition>(base + Instance,
                                                             Instance);
            } else {
                return spawn_result::invalid_entry;
            }
        } else {
            if constexpr (declared_task_definition<Definition>) {
                base += Definition::instances;
            } else if constexpr (dynamic_task_definition<Definition>) {
                base += Definition::count;
            }
            if constexpr (sizeof...(Rest) > 0U) {
                return start_entry<Entry, Instance, Rest...>(base);
            } else {
                return spawn_result::invalid_entry;
            }
        }
    }
 
    template<auto Entry,
             std::size_t Instance,
             typename Definition,
             typename... Rest>
    [[nodiscard]] bool find_entry(std::size_t& base, std::size_t& task_id) const
    {
        if constexpr (declared_task_definition<Definition> &&
                      same_task_entry<Definition::entry, Entry>) {
            if constexpr (Instance < Definition::instances) {
                task_id = base + Instance;
                return true;
            } else {
                return false;
            }
        } else {
            if constexpr (declared_task_definition<Definition>) {
                base += Definition::instances;
            } else if constexpr (dynamic_task_definition<Definition>) {
                base += Definition::count;
            }
            if constexpr (sizeof...(Rest) > 0U) {
                return find_entry<Entry, Instance, Rest...>(base, task_id);
            } else {
                return false;
            }
        }
    }
 
    Runtime* runtime_{};
    tsm::static_coroutine_arena<arena_bytes> arena_{};
    std::array<tsm::task_context, task_count> contexts_{};
    std::array<tsm::task, task_count> tasks_{};
    std::array<std::size_t, task_count> ready_queue_{};
    std::array<std::uint8_t, task_count> priorities_{};
    timer_queue<task_count> timers_{};
    std::size_t ready_push_{};
    std::size_t ready_pop_{};
    std::size_t ready_size_{};
    tsm::tick_rep now_{};
    std::uint32_t timer_sequence_{};
};
 
template<typename Runtime>
using coroutine_scheduler_for =
  coroutine_scheduler<Runtime, typename runtime_task_list_of<Runtime>::type>;
 
template<typename Runtime>
using priority_coroutine_scheduler_for =
  coroutine_scheduler<Runtime,
                      typename runtime_task_list_of<Runtime>::type,
                      true>;
 
template<typename Runtime, template<typename> typename SchedulerFor>
class basic_executor_task_binding
{
  public:
    explicit basic_executor_task_binding(Runtime& runtime)
      : runtime_(&runtime)
      , coroutines_(runtime)
    {
    }
 
    [[nodiscard]] bool step()
    {
        // Task code and HSM dispatch share a cooperative turn. A task runs
        // first if already ready; otherwise the runtime processes one event and
        // predicate waits are checked before one more task opportunity.
        if (coroutines_.step()) {
            return true;
        }
        if (runtime_->step()) {
            static_cast<void>(coroutines_.poll_waiting());
            return true;
        }
        static_cast<void>(coroutines_.poll_waiting());
        return coroutines_.step();
    }
 
    std::size_t run_ready()
    {
        std::size_t rounds{};
        while (step()) {
            ++rounds;
        }
        return rounds;
    }
 
    std::size_t tick(tsm::tick_rep elapsed_ticks = 1U)
    {
        return coroutines_.tick(elapsed_ticks);
    }
 
    std::size_t tick(tsm::tick_count elapsed_ticks)
    {
        return tick(elapsed_ticks.count());
    }
 
    void start_all()
    {
        coroutines_.start_all();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] spawn_result start()
    {
        return coroutines_.template start<Entry, Instance>();
    }
 
    template<auto Entry, typename... Args>
    [[nodiscard]] spawn_result spawn(Args&&... args)
    {
        return coroutines_.template spawn<Entry>(std::forward<Args>(args)...);
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] task_status task_status() const
    {
        return coroutines_.template status<Entry, Instance>();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] task_failure_reason task_failure_reason() const
    {
        return coroutines_.template failure_reason<Entry, Instance>();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] bool cancel() noexcept
    {
        return coroutines_.template cancel<Entry, Instance>();
    }
 
    void cancel_all() noexcept
    {
        coroutines_.cancel_all();
    }
 
  private:
    Runtime* runtime_{};
    SchedulerFor<Runtime> coroutines_;
};
 
template<typename Runtime>
using executor_task_binding =
  basic_executor_task_binding<Runtime, coroutine_scheduler_for>;
 
template<typename Runtime>
using priority_executor_task_binding =
  basic_executor_task_binding<Runtime, priority_coroutine_scheduler_for>;
 
} // namespace detail
 
template<std::size_t Capacity>
using timer_queue = detail::timer_queue<Capacity>;
 
template<typename Runtime>
using task_resources = detail::task_resources<Runtime>;
 
} // namespace runtime
 
} // namespace tsm