task.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/chrono>
#include <idfxx/cpu>
#include <idfxx/error>
#include <idfxx/memory>
 
#include <chrono>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <system_error>
#include <type_traits>
#include <utility>
 
namespace idfxx {
 
class task {
    struct context;
 
public:
    enum class errc : esp_err_t {
        would_deadlock = 1, 
    };
 
    class error_category : public std::error_category {
    public:
        [[nodiscard]] const char* name() const noexcept override final;
 
        [[nodiscard]] std::string message(int ec) const override final;
 
        [[nodiscard]] bool equivalent(int code, const std::error_condition& condition) const noexcept override final;
    };
 
    class self {
        friend class task;
        explicit self(context* ctx) noexcept
            : _context(ctx) {}
 
    public:
        self(const self&) = delete;
        self& operator=(const self&) = delete;
 
        [[nodiscard]] bool is_detached() const noexcept;
 
        [[nodiscard]] bool stop_requested() const noexcept;
 
        void suspend() noexcept;
 
        void wait() noexcept;
 
        template<typename Rep, typename Period>
        bool wait_for(const std::chrono::duration<Rep, Period>& timeout) noexcept {
            return _take(chrono::ticks(timeout)) != 0;
        }
 
        template<typename Clock, typename Duration>
        bool wait_until(const std::chrono::time_point<Clock, Duration>& deadline) noexcept {
            auto remaining = deadline - Clock::now();
            if (remaining <= decltype(remaining)::zero()) {
                return _take(0) != 0;
            }
            return _take(chrono::ticks(remaining)) != 0;
        }
 
        uint32_t take() noexcept;
 
        template<typename Rep, typename Period>
        uint32_t take_for(const std::chrono::duration<Rep, Period>& timeout) noexcept {
            return _take(chrono::ticks(timeout));
        }
 
        template<typename Clock, typename Duration>
        uint32_t take_until(const std::chrono::time_point<Clock, Duration>& deadline) noexcept {
            auto remaining = deadline - Clock::now();
            if (remaining <= decltype(remaining)::zero()) {
                return _take(0);
            }
            return _take(chrono::ticks(remaining));
        }
 
        [[nodiscard]] task_priority priority() const noexcept;
 
        void set_priority(task_priority new_priority) noexcept;
 
        [[nodiscard]] size_t stack_high_water_mark() const noexcept;
 
        [[nodiscard]] std::string name() const;
 
        [[nodiscard]] TaskHandle_t idf_handle() const noexcept;
 
    private:
        uint32_t _take(TickType_t ticks) noexcept;
 
        context* _context;
    };
 
    struct config {
        std::string_view name = "task";                                     
        size_t stack_size = 4096;                                           
        task_priority priority = 5;                                         
        std::optional<core_id> core_affinity = std::nullopt;                
        flags<memory::capabilities> stack_mem = memory::capabilities::dram; 
    };
 
    [[nodiscard]] explicit task(const config& cfg, std::move_only_function<void(self&)> task_func);
 
    static void spawn(config cfg, std::move_only_function<void(self&)> task_func);
 
    ~task();
 
    task(const task&) = delete;
    task& operator=(const task&) = delete;
    task(task&& other) noexcept;
    task& operator=(task&& other) noexcept;
 
    [[nodiscard]] TaskHandle_t idf_handle() const noexcept { return _handle; }
 
    [[nodiscard]] const std::string& name() const noexcept { return _name; }
 
    [[nodiscard]] task_priority priority() const noexcept;
 
    [[nodiscard]] size_t stack_high_water_mark() const noexcept;
 
    [[nodiscard]] bool is_completed() const noexcept;
 
    [[nodiscard]] bool joinable() const noexcept { return _handle != nullptr; }
 
    bool request_stop() noexcept;
 
    [[nodiscard]] bool stop_requested() const noexcept;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void suspend() { unwrap(try_suspend()); }
 
    void resume() { unwrap(try_resume()); }
#endif
 
    result<void> try_suspend();
 
    result<void> try_resume();
 
    [[nodiscard]] bool resume_from_isr() noexcept;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void notify() { unwrap(try_notify()); }
#endif
 
    result<void> try_notify();
 
    [[nodiscard]] bool notify_from_isr() noexcept;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_priority(task_priority new_priority) { unwrap(try_set_priority(new_priority)); }
#endif
 
    [[nodiscard]] result<void> try_set_priority(task_priority new_priority);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void detach() { unwrap(try_detach()); }
#endif
 
    result<void> try_detach();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void kill() { unwrap(try_kill()); }
#endif
 
    result<void> try_kill();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void join() { unwrap(try_join()); }
 
    template<typename Rep, typename Period>
    void join(const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_join(timeout));
    }
 
    template<typename Clock, typename Duration>
    void join_until(const std::chrono::time_point<Clock, Duration>& deadline) {
        unwrap(try_join_until(deadline));
    }
#endif
 
    [[nodiscard]] result<void> try_join();
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_join(const std::chrono::duration<Rep, Period>& timeout) {
        return _try_join(chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<void> try_join_until(const std::chrono::time_point<Clock, Duration>& deadline) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_join(0);
        }
        return _try_join(chrono::ticks(remaining));
    }
 
    // =========================================================================
    // Static utility methods for current task operations
    // =========================================================================
 
    [[nodiscard]] static TaskHandle_t current_handle() noexcept { return xTaskGetCurrentTaskHandle(); }
 
    [[nodiscard]] static std::string current_name() { return pcTaskGetName(nullptr); }
 
private:
    static void trampoline(void* arg);
 
    static TaskHandle_t _create(context* ctx, const config& cfg, const char* name);
    [[nodiscard]] result<void> _try_join(TickType_t ticks);
    void _stop_and_delete() noexcept;
    [[nodiscard]] bool _is_running() const noexcept;
 
    explicit task(TaskHandle_t handle, std::string name, context* ctx);
 
    TaskHandle_t _handle = nullptr;
    std::string _name;
    context* _context = nullptr;
};
 
[[nodiscard]] const task::error_category& task_category() noexcept;
 
[[nodiscard]] inline std::error_code make_error_code(task::errc e) noexcept {
    return {std::to_underlying(e), task_category()};
}
 
 
} // namespace idfxx
 
namespace std {
template<>
struct is_error_code_enum<idfxx::task::errc> : true_type {};
} // namespace std