executor.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 <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <tuple>
#include <type_traits>
#include <utility>
 
#ifndef TSM_SUPPRESS_AUTO_PLATFORM_ADAPTERS
#define TSM_SUPPRESS_AUTO_PLATFORM_ADAPTERS
#define TSM_RESTORE_AUTO_PLATFORM_ADAPTERS
#endif
#include "tsm.h"
#ifdef TSM_RESTORE_AUTO_PLATFORM_ADAPTERS
#undef TSM_SUPPRESS_AUTO_PLATFORM_ADAPTERS
#undef TSM_RESTORE_AUTO_PLATFORM_ADAPTERS
#endif
#include "tsm/runtime/concepts.h"
#include "tsm/runtime/coroutine.h"
 
namespace tsm::runtime {
 
struct inline_executor
{
    template<typename Work>
    decltype(auto) post(Work&& work)
    {
        return std::forward<Work>(work)();
    }
 
    [[nodiscard]] bool step()
    {
        return false;
    }
    std::size_t run_ready()
    {
        return 0;
    }
};
 
template<typename... Runtimes>
class runtime_group
{
  public:
    explicit constexpr runtime_group(Runtimes&... runtimes)
      : runtimes_(&runtimes...)
    {
    }
 
    [[nodiscard]] bool step()
    {
        bool progressed{};
        std::apply(
          [&progressed](auto*... runtime) {
              ((progressed = runtime->step() || progressed), ...);
          },
          runtimes_);
        return progressed;
    }
 
    std::size_t run_ready()
    {
        std::size_t rounds{};
        while (step()) {
            ++rounds;
        }
        return rounds;
    }
 
    [[nodiscard]] bool empty() const
    {
        bool all_empty{ true };
        std::apply(
          [&all_empty](auto const*... runtime) {
              ((all_empty = all_empty && runtime->empty()), ...);
          },
          runtimes_);
        return all_empty;
    }
 
    [[nodiscard]] std::size_t pending_events() const
    {
        std::size_t pending{};
        std::apply(
          [&pending](auto const*... runtime) {
              ((pending += runtime->pending_events()), ...);
          },
          runtimes_);
        return pending;
    }
 
  private:
    std::tuple<Runtimes*...> runtimes_;
};
 
template<typename... Runtimes>
runtime_group(Runtimes&...) -> runtime_group<Runtimes...>;
 
template<typename Executor>
class task_spawner
{
  public:
    explicit constexpr task_spawner(Executor& executor)
      : executor_(&executor)
    {
    }
 
    template<auto Entry, typename... Args>
    [[nodiscard]] spawn_result spawn(Args&&... args)
    {
        return executor_->template spawn<Entry>(std::forward<Args>(args)...);
    }
 
  private:
    Executor* executor_{};
};
 
template<typename Executor>
using spawner = task_spawner<Executor>;
 
template<template<typename> typename Binding, typename... Tasks>
class basic_cooperative_executor
{
  public:
    explicit constexpr basic_cooperative_executor(Tasks&... tasks)
      : tasks_(tasks...)
    {
    }
 
    [[nodiscard]] bool step()
    {
        bool progressed{};
        std::apply(
          [&progressed](auto&... task) {
              ((progressed = task.step() || progressed), ...);
          },
          tasks_);
        return progressed;
    }
 
    std::size_t run_ready()
    {
        std::size_t rounds{};
        while (step()) {
            ++rounds;
        }
        return rounds;
    }
 
    std::size_t tick(tsm::tick_rep elapsed_ticks = 1U)
    {
        std::size_t resumed{};
        std::apply(
          [&resumed, elapsed_ticks](auto&... task) {
              ((resumed += task.tick(elapsed_ticks)), ...);
          },
          tasks_);
        return resumed;
    }
 
    std::size_t tick(tsm::tick_count elapsed_ticks)
    {
        return tick(elapsed_ticks.count());
    }
 
    void start_all()
    {
        // Forward to runtime task bindings. Runtime definitions decide which
        // declared coroutine tasks exist; the executor only starts them.
        std::apply([](auto&... task) { (task.start_all(), ...); }, tasks_);
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] spawn_result start()
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: start<Entry, Instance>() is available on a "
                      "single-runtime executor");
        return std::get<0>(tasks_).template start<Entry, Instance>();
    }
 
    template<auto... Entries>
    void start_group(tsm::task_group<Entries...>)
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: start_group(...) is available on a "
                      "single-runtime executor");
        (static_cast<void>(start<Entries>()), ...);
    }
 
    template<auto Entry, typename... Args>
    [[nodiscard]] spawn_result spawn(Args&&... args)
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: spawn<Entry>() is available on a "
                      "single-runtime executor");
        // Dynamic task spawning is intentionally scoped to one runtime so the
        // entry point cannot be ambiguous across a runtime group.
        return std::get<0>(tasks_).template spawn<Entry>(
          std::forward<Args>(args)...);
    }
 
    [[nodiscard]] task_spawner<basic_cooperative_executor> spawner()
    {
        return task_spawner<basic_cooperative_executor>{ *this };
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] task_status task_status() const
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: task_status<Entry, Instance>() is available on a "
                      "single-runtime executor");
        return std::get<0>(tasks_).template task_status<Entry, Instance>();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] task_failure_reason task_failure_reason() const
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: task_failure_reason<Entry, Instance>() is "
                      "available on a single-runtime executor");
        return std::get<0>(tasks_)
          .template task_failure_reason<Entry, Instance>();
    }
 
    template<auto Entry, std::size_t Instance = 0U>
    [[nodiscard]] bool cancel() noexcept
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: cancel<Entry, Instance>() is available on a "
                      "single-runtime executor");
        return std::get<0>(tasks_).template cancel<Entry, Instance>();
    }
 
    template<auto... Entries>
    void cancel_group(tsm::task_group<Entries...>) noexcept
    {
        static_assert(sizeof...(Tasks) == 1U,
                      "tsm: cancel_group(...) is available on a "
                      "single-runtime executor");
        (static_cast<void>(cancel<Entries>()), ...);
    }
 
    void cancel_all() noexcept
    {
        std::apply([](auto&... task) { (task.cancel_all(), ...); }, tasks_);
    }
 
  private:
    std::tuple<Binding<Tasks>...> tasks_;
};
 
template<typename... Tasks>
class cooperative_executor
  : public basic_cooperative_executor<detail::executor_task_binding, Tasks...>
{
    using base =
      basic_cooperative_executor<detail::executor_task_binding, Tasks...>;
 
  public:
    using base::base;
};
 
template<typename... Tasks>
cooperative_executor(Tasks&...) -> cooperative_executor<Tasks...>;
 
template<typename... Tasks>
class priority_cooperative_executor
  : public basic_cooperative_executor<detail::priority_executor_task_binding,
                                      Tasks...>
{
    using base =
      basic_cooperative_executor<detail::priority_executor_task_binding,
                                 Tasks...>;
 
  public:
    using base::base;
};
 
template<typename... Tasks>
priority_cooperative_executor(Tasks&...)
  -> priority_cooperative_executor<Tasks...>;
 
template<typename TickSource, typename Executor, typename DelayedEvents>
[[nodiscard]] tsm::tick_rep
drive_elapsed_ticks(TickSource& tick_source,
                    Executor& executor,
                    DelayedEvents& delayed_events)
{
    const auto elapsed_ticks = tsm::ticks(tick_source.poll());
    if (elapsed_ticks.count() == 0U) {
        return tsm::tick_rep{};
    }
 
    static_cast<void>(executor.tick(elapsed_ticks));
    static_cast<void>(delayed_events.tick(elapsed_ticks));
    static_cast<void>(executor.run_ready());
    return elapsed_ticks.count();
}
 
template<typename Runtime, std::size_t Capacity = 16U>
class tick_executor
{
  public:
    using runtime_type = Runtime;
    using events = typename Runtime::events;
    using event_list = tsm::detail::as_type_list_t<events>;
 
    static_assert(Capacity > 0U,
                  "tsm: tick_executor requires at least one timer slot");
 
    explicit constexpr tick_executor(Runtime& runtime)
      : runtime_(&runtime)
    {
    }
 
    template<typename Event>
    requires(tsm::detail::contains_type<std::decay_t<Event>>(
      tsm::detail::as_type_list_t<events>{}))
      [[nodiscard]] bool after_ticks(Event&& event, tsm::tick_rep ticks)
    {
        return schedule(std::forward<Event>(event), ticks, 0U, false);
    }
 
    template<typename Event>
    requires(tsm::detail::contains_type<std::decay_t<Event>>(
      tsm::detail::as_type_list_t<events>{}))
      [[nodiscard]] bool after_ticks(Event&& event, tsm::tick_count ticks)
    {
        return after_ticks(std::forward<Event>(event), ticks.count());
    }
 
    template<typename Event>
    requires(tsm::detail::contains_type<std::decay_t<Event>>(
      tsm::detail::as_type_list_t<events>{}))
      [[nodiscard]] bool every_ticks(Event&& event, tsm::tick_rep period)
    {
        return period != 0U &&
               schedule(std::forward<Event>(event), period, period, true);
    }
 
    template<typename Event>
    requires(tsm::detail::contains_type<std::decay_t<Event>>(
      tsm::detail::as_type_list_t<events>{}))
      [[nodiscard]] bool every_ticks(Event&& event, tsm::tick_count period)
    {
        return every_ticks(std::forward<Event>(event), period.count());
    }
 
    std::size_t tick(tsm::tick_rep elapsed_ticks = 1U)
    {
        std::size_t sent{};
        tsm::tick_rep remaining_elapsed = elapsed_ticks;
        while (remaining_elapsed > 0U) {
            const tsm::tick_rep tick_step = next_step(remaining_elapsed);
            advance(tick_step);
            remaining_elapsed -= tick_step;
            sent += send_due();
        }
        return sent;
    }
 
    std::size_t tick(tsm::tick_count elapsed_ticks)
    {
        return tick(elapsed_ticks.count());
    }
 
    [[nodiscard]] bool step()
    {
        return false;
    }
    std::size_t run_ready()
    {
        return 0;
    }
 
    [[nodiscard]] std::size_t pending() const
    {
        return static_cast<std::size_t>(
          std::count_if(timers_.begin(), timers_.end(), [](auto const& timer) {
              return timer.active;
          }));
    }
 
    [[nodiscard]] bool empty() const
    {
        return pending() == 0U;
    }
 
    void clear()
    {
        std::fill(timers_.begin(), timers_.end(), timer_slot{});
    }
 
  private:
    class scheduled_event
    {
      public:
        static constexpr std::size_t storage_size =
          tsm::detail::max_sizeof(event_list{});
        static constexpr std::size_t storage_alignment =
          tsm::detail::max_alignof(event_list{});
 
        scheduled_event() = default;
        scheduled_event(scheduled_event const& other)
        {
            copy_from(other);
        }
        scheduled_event(scheduled_event&& other) noexcept
        {
            move_from(other);
        }
 
        scheduled_event& operator=(scheduled_event const& other)
        {
            if (this != &other) {
                reset();
                storage_ = {};
                copy_from(other);
            }
            return *this;
        }
 
        scheduled_event& operator=(scheduled_event&& other) noexcept
        {
            if (this != &other) {
                reset();
                storage_ = {};
                move_from(other);
            }
            return *this;
        }
 
        ~scheduled_event()
        {
            reset();
        }
 
        template<typename Event>
        requires(!std::same_as<
                 std::decay_t<Event>,
                 scheduled_event>) explicit scheduled_event(Event&& event)
        {
            emplace<std::decay_t<Event>>(std::forward<Event>(event));
        }
 
        [[nodiscard]] bool empty() const
        {
            return send_ == nullptr;
        }
 
        bool send(Runtime& runtime)
        {
            if (send_ == nullptr) {
                return false;
            }
            return send_(runtime, data());
        }
 
      private:
        using send_fn = bool (*)(Runtime&, void*);
        using copy_fn = void (*)(void*, void const*);
        using move_fn = void (*)(void*, void*);
        using destroy_fn = void (*)(void*);
 
        template<typename Event, typename... Args>
        void emplace(Args&&... args)
        {
            static_assert(sizeof(Event) <= storage_size);
            static_assert(alignof(Event) <= storage_alignment);
            new (data()) Event(std::forward<Args>(args)...);
            send_ = [](Runtime& runtime, void* storage) -> bool {
                return runtime.send_event(*static_cast<Event*>(storage));
            };
            copy_ = [](void* destination, void const* source) {
                new (destination) Event(*static_cast<Event const*>(source));
            };
            move_ = [](void* destination, void* source) {
                new (destination)
                  Event(std::move(*static_cast<Event*>(source)));
            };
            destroy_ = [](void* storage) {
                static_cast<Event*>(storage)->~Event();
            };
        }
 
        void copy_from(scheduled_event const& other)
        {
            if (other.copy_ == nullptr) {
                return;
            }
            other.copy_(data(), other.data());
            send_ = other.send_;
            copy_ = other.copy_;
            move_ = other.move_;
            destroy_ = other.destroy_;
        }
 
        void move_from(scheduled_event& other)
        {
            if (other.move_ == nullptr) {
                return;
            }
            other.move_(data(), other.data());
            send_ = other.send_;
            copy_ = other.copy_;
            move_ = other.move_;
            destroy_ = other.destroy_;
            other.reset();
        }
 
        void reset()
        {
            if (destroy_ != nullptr) {
                destroy_(data());
            }
            send_ = nullptr;
            copy_ = nullptr;
            move_ = nullptr;
            destroy_ = nullptr;
        }
 
        void* data()
        {
            return storage_.data();
        }
        void const* data() const
        {
            return storage_.data();
        }
 
        alignas(
          storage_alignment) std::array<unsigned char, storage_size> storage_{};
        send_fn send_{};
        copy_fn copy_{};
        move_fn move_{};
        destroy_fn destroy_{};
    };
 
    struct timer_slot
    {
        scheduled_event event{};
        tsm::tick_rep remaining{};
        tsm::tick_rep period{};
        bool periodic{};
        bool active{};
    };
 
    template<typename Event>
    [[nodiscard]] bool schedule(Event&& event,
                                tsm::tick_rep ticks,
                                tsm::tick_rep period,
                                bool periodic)
    {
        auto slot =
          std::find_if(timers_.begin(), timers_.end(), [](auto const& timer) {
              return !timer.active;
          });
        if (slot != timers_.end()) {
            slot->event = scheduled_event(std::forward<Event>(event));
            slot->remaining = ticks;
            slot->period = period;
            slot->periodic = periodic;
            slot->active = true;
            return true;
        }
        return false;
    }
 
    [[nodiscard]] tsm::tick_rep next_step(tsm::tick_rep elapsed_limit) const
    {
        tsm::tick_rep tick_step = elapsed_limit;
        for (auto const& timer : timers_) {
            if (!timer.active) {
                continue;
            }
            if (timer.remaining == 0U) {
                return 1U;
            }
            if (timer.remaining < tick_step) {
                tick_step = timer.remaining;
            }
        }
        return tick_step;
    }
 
    void advance(tsm::tick_rep ticks)
    {
        for (auto& timer : timers_) {
            if (!timer.active) {
                continue;
            }
            if (timer.remaining > ticks) {
                timer.remaining -= ticks;
            } else {
                timer.remaining = 0U;
            }
        }
    }
 
    std::size_t send_due()
    {
        std::size_t sent{};
        for (auto& timer : timers_) {
            if (!timer.active || timer.remaining != 0U) {
                continue;
            }
            ++sent;
            if (timer.periodic) {
                auto event = timer.event;
                (void)event.send(*runtime_);
                timer.remaining = timer.period;
            } else {
                (void)timer.event.send(*runtime_);
                timer = timer_slot{};
            }
        }
        return sent;
    }
 
    Runtime* runtime_{};
    std::array<timer_slot, Capacity> timers_{};
};
 
template<typename Runtime>
tick_executor(Runtime&) -> tick_executor<Runtime>;
 
template<typename Runtime, std::size_t Capacity = 16U>
using delayed_event_timer = tick_executor<Runtime, Capacity>;
 
} // namespace tsm::runtime