thread.hpp

Go to the documentation of this file.

/*
 * Copyright (C) 2026 Kamil Lulko <kamil.lulko@gmail.com>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * This file is part of oveRTOS.
 */
 
#pragma once
 
#include <ove/thread.h>
#include <ove/types.hpp>
 
#ifndef CONFIG_OVE_ZERO_HEAP
#include <memory> /* std::unique_ptr in the capturing trampoline */
#endif
 
namespace ove
{
 
/* ── Cooperative cancellation token ─────────────────────────────────── */
 
class stop_token
{
      public:
    constexpr stop_token() noexcept = default;
    constexpr explicit stop_token(ove_thread_t h) noexcept : handle_(h)
    {
    }
 
    [[nodiscard]] bool stop_requested() const noexcept
    {
        return handle_ != nullptr && ove_thread_should_stop(handle_);
    }
 
    [[nodiscard]] bool stop_possible() const noexcept
    {
        return handle_ != nullptr;
    }
 
    explicit operator bool() const noexcept
    {
        return stop_requested();
    }
 
    [[nodiscard]] ove_thread_t handle() const noexcept
    {
        return handle_;
    }
 
      private:
    ove_thread_t handle_ = nullptr;
};
 
class stop_source
{
      public:
    constexpr stop_source() noexcept = default;
    constexpr explicit stop_source(ove_thread_t h) noexcept : handle_(h)
    {
    }
 
    bool request_stop() noexcept
    {
        if (handle_ == nullptr)
            return false;
        const bool was_stopped = ove_thread_should_stop(handle_);
        if (!was_stopped)
            ove_thread_request_stop(handle_);
        return !was_stopped;
    }
 
    [[nodiscard]] bool stop_requested() const noexcept
    {
        return handle_ != nullptr && ove_thread_should_stop(handle_);
    }
 
    [[nodiscard]] bool stop_possible() const noexcept
    {
        return handle_ != nullptr;
    }
 
    explicit operator bool() const noexcept
    {
        return stop_requested();
    }
 
    [[nodiscard]] stop_token get_token() const noexcept
    {
        return stop_token{handle_};
    }
 
    [[nodiscard]] ove_thread_t handle() const noexcept
    {
        return handle_;
    }
 
    friend constexpr bool operator==(const stop_source &,
                     const stop_source &) noexcept = default;
 
      private:
    ove_thread_t handle_ = nullptr;
};
 
template <typename F>
concept CooperativeThreadEntry = std::convertible_to<F, void (*)(stop_token)>;
 
#ifndef CONFIG_OVE_ZERO_HEAP
template <typename F>
concept CapturingCooperativeEntry =
    std::invocable<F &, stop_token> && !std::convertible_to<F, void (*)(stop_token)>;
#endif
 
class thread_id
{
      public:
    constexpr thread_id() noexcept = default;
    constexpr explicit thread_id(ove_thread_t h) noexcept : handle_(h)
    {
    }
 
    friend constexpr bool operator==(const thread_id &, const thread_id &) noexcept = default;
    friend constexpr auto operator<=>(const thread_id &, const thread_id &) noexcept = default;
 
    [[nodiscard]] ove_thread_t native_handle() const noexcept
    {
        return handle_;
    }
 
      private:
    ove_thread_t handle_ = nullptr;
};
 
namespace detail
{
 
/* Trampoline bridging the substrate's `void(void*)` entry signature to
 * the cooperative `void(stop_token)` user signature.
 *
 * The user's function pointer is passed verbatim through `ctx` via
 * reinterpret_cast — guarded by a compile-time size check on every
 * supported target (function pointer and data pointer share width on
 * POSIX, ARM Cortex-M, and Xtensa).
 *
 * Token construction uses `ove_thread_get_self()` after a brief poll
 * loop: on some backends (notably FreeRTOS) the task-tag lookup that
 * powers `get_self` is populated by the spawning thread AFTER the new
 * thread starts running, so the first call may return NULL.  Yielding
 * lets the spawner finish the tag publish. */
inline void stop_token_trampoline(void *ctx)
{
    static_assert(sizeof(void *) == sizeof(void (*)(stop_token)),
              "ove::stop_token trampoline requires function and data pointers "
              "to share width — fix by adding a per-target trampoline shim");
    auto user_fn = reinterpret_cast<void (*)(stop_token)>(ctx);
    ove_thread_t self;
    while ((self = ove_thread_get_self()) == nullptr) {
        ove_thread_yield();
    }
    user_fn(stop_token{self});
}
 
#ifndef CONFIG_OVE_ZERO_HEAP
/* Trampoline for the heap-mode capturing cooperative constructor.
 *
 * `ctx` is a `new`-allocated closure of type F that the constructor
 * minted; the trampoline reclaims it via std::unique_ptr so the box
 * is delete'd after the entry returns (or if the entry throws,
 * though our binding requires noexcept user code in practice).
 *
 * One template instantiation per F — the closure's exact type is
 * preserved, no type erasure or virtual dispatch.  Each instantiation
 * is small (typically 1-2 cache lines after LLVM inlining), so the
 * code-size cost scales with the number of distinct capturing
 * lambdas, not with the number of spawn sites. */
template <typename F> inline void capturing_trampoline(void *ctx)
{
    std::unique_ptr<F> f{static_cast<F *>(ctx)};
    ove_thread_t self;
    while ((self = ove_thread_get_self()) == nullptr) {
        ove_thread_yield();
    }
    (*f)(stop_token{self});
}
#endif
 
} // namespace detail
 
template <size_t StackSize = 0> class Thread
{
      public:
    using id = thread_id;
 
    template <typename F>
    Thread(F entry, void *ctx, ove_prio_t prio, const char *name)
        requires(StackSize > 0) && ThreadEntry<F>
    {
#ifdef CONFIG_OVE_ZERO_HEAP
        static_assert(StackSize > 0, "StackSize must be > 0 in zero-heap mode");
        int err = ove_thread_init(&handle_, &storage_, name, entry, ctx, prio, StackSize,
                      stack_);
#else
        int err = ove_thread_create(&handle_, name, entry, ctx, prio, StackSize);
#endif
        OVE_STATIC_INIT_ASSERT(err == OVE_OK);
    }
 
    template <typename F>
    Thread(F entry, ove_prio_t prio, const char *name)
        requires(StackSize > 0) && CooperativeThreadEntry<F>
    {
        void (*fn)(stop_token) = entry;
        void *ctx = reinterpret_cast<void *>(fn);
#ifdef CONFIG_OVE_ZERO_HEAP
        static_assert(StackSize > 0, "StackSize must be > 0 in zero-heap mode");
        int err = ove_thread_init(&handle_, &storage_, name, &detail::stop_token_trampoline,
                      ctx, prio, StackSize, stack_);
#else
        int err = ove_thread_create(&handle_, name, &detail::stop_token_trampoline, ctx,
                        prio, StackSize);
#endif
        OVE_STATIC_INIT_ASSERT(err == OVE_OK);
    }
 
#ifndef CONFIG_OVE_ZERO_HEAP
    template <typename F>
    Thread(F &&entry, ove_prio_t prio, const char *name)
        requires(StackSize > 0) && CapturingCooperativeEntry<std::decay_t<F>>
    {
        using FT = std::decay_t<F>;
        FT *boxed = new FT(std::forward<F>(entry));
        int err = ove_thread_create(&handle_, name, &detail::capturing_trampoline<FT>,
                        boxed, prio, StackSize);
        if (err != OVE_OK) {
            delete boxed; /* trampoline never runs; reclaim the box */
            OVE_STATIC_INIT_ASSERT(err == OVE_OK);
        }
    }
#endif
 
    ~Thread() noexcept
    {
        if (!handle_)
            return;
        ove_thread_request_stop(handle_);
#ifdef CONFIG_OVE_ZERO_HEAP
        ove_thread_deinit(handle_);
#else
        ove_thread_destroy(handle_);
#endif
    }
 
    Thread(const Thread &) = delete;
    Thread &operator=(const Thread &) = delete;
 
#ifdef CONFIG_OVE_ZERO_HEAP
    Thread(Thread &&) = delete;
    Thread &operator=(Thread &&) = delete;
#else
    Thread(Thread &&other) noexcept : handle_(other.handle_)
    {
        other.handle_ = nullptr;
    }
 
    Thread &operator=(Thread &&other) noexcept
    {
        if (this != &other) {
            if (handle_)
                ove_thread_destroy(handle_);
            handle_ = other.handle_;
            other.handle_ = nullptr;
        }
        return *this;
    }
#endif
 
    void join() noexcept
    {
        if (!handle_)
            return;
#ifdef CONFIG_OVE_ZERO_HEAP
        ove_thread_deinit(handle_);
#else
        ove_thread_destroy(handle_);
#endif
        handle_ = nullptr;
    }
 
#ifdef CONFIG_OVE_ZERO_HEAP
    void detach() = delete;
#else
    void detach() noexcept
    {
        handle_ = nullptr;
    }
#endif
 
    void set_priority(ove_prio_t prio)
    {
        ove_thread_set_priority(handle_, prio);
    }
 
    void suspend()
    {
        ove_thread_suspend(handle_);
    }
 
    void resume()
    {
        ove_thread_resume(handle_);
    }
 
    ove_thread_state_t get_state() const
    {
        return ove_thread_get_state(handle_);
    }
 
    size_t get_stack_usage() const
    {
        return ove_thread_get_stack_usage(handle_);
    }
 
    [[nodiscard]] Result<struct ove_thread_stats> get_runtime_stats() const noexcept
    {
        struct ove_thread_stats stats {
        };
        const int rc = ove_thread_get_runtime_stats(handle_, &stats);
        return from_rc(rc, stats);
    }
 
    void request_stop() noexcept
    {
        if (handle_)
            ove_thread_request_stop(handle_);
    }
 
    [[nodiscard]] stop_token get_stop_token() const noexcept
    {
        return stop_token{handle_};
    }
 
    [[nodiscard]] stop_source get_stop_source() const noexcept
    {
        return stop_source{handle_};
    }
 
    [[nodiscard]] bool stop_requested() const noexcept
    {
        return handle_ != nullptr && ove_thread_should_stop(handle_);
    }
 
    bool valid() const
    {
        return handle_ != nullptr;
    }
 
    [[nodiscard]] bool joinable() const noexcept
    {
        return handle_ != nullptr;
    }
 
    [[nodiscard]] id get_id() const noexcept
    {
        return id{handle_};
    }
 
    ove_thread_t handle() const
    {
        return handle_;
    }
 
      private:
    ove_thread_t handle_ = nullptr;
#ifdef CONFIG_OVE_ZERO_HEAP
    /* `stack_` precedes `storage_` so the latter (whose underlying C
     * struct ends in a flexible-array `stack[]`) sits at the end of the
     * C++ class.  C99 allows FAMs anywhere in a struct, but C++ rejects
     * another member after one — see
     * backends/freertos/include/ove_storage_freertos.h FAM commentary. */
    OVE_THREAD_STACK_MEMBER_(stack_, StackSize > 0 ? StackSize : 1);
    ove_thread_storage_t storage_ = {};
#endif
};
 
/* ── System memory statistics ──────────────────────────────────── */
 
struct MemStats {
    size_t total{};     
    size_t free{};      
    size_t used{};      
    size_t peak_used{}; 
};
 
[[nodiscard]] inline Result<MemStats> get_mem_stats() noexcept
{
    MemStats stats{};
    struct ove_mem_stats ms {
    };
    const int rc = ove_sys_get_mem_stats(&ms);
    if (rc == OVE_OK) {
        stats.total = ms.total;
        stats.free = ms.free;
        stats.used = ms.used;
        stats.peak_used = ms.peak_used;
    }
    return from_rc(rc, stats);
}
 
/* ── Thread enumeration ───────────────────────────────────────── */
 
using ThreadInfo = struct ove_thread_info;
 
[[nodiscard]] inline Result<size_t> thread_list(ThreadInfo *out, size_t max) noexcept
{
    size_t n = 0;
    const int rc = ove_thread_list(out, max, &n);
    return from_rc(rc, n);
}
 
} /* namespace ove */
 
namespace ove::this_thread
{
 
inline void sleep_ms(uint32_t ms) noexcept
{
    ove_thread_sleep_ms(ms);
}
 
template <typename Rep, typename Period>
inline void sleep_for(std::chrono::duration<Rep, Period> d) noexcept
{
    const auto ms = std::chrono::duration_cast<std::chrono::milliseconds>(d).count();
    ove_thread_sleep_ms(ms > 0 ? static_cast<uint32_t>(ms) : 0u);
}
 
inline void yield() noexcept
{
    ove_thread_yield();
}
 
inline ove_thread_t self() noexcept
{
    return ove_thread_get_self();
}
 
inline thread_id get_id() noexcept
{
    return thread_id{ove_thread_get_self()};
}
 
} /* namespace ove::this_thread */