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 <memory>
#include <optional>
#include <string>
#include <string_view>
 
namespace idfxx {
 
class task {
    struct context;
 
public:
    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>
        [[nodiscard]] bool wait_for(const std::chrono::duration<Rep, Period>& timeout) noexcept {
            return _take(chrono::ticks(timeout)) != 0;
        }
 
        template<typename Clock, typename Duration>
        [[nodiscard]] 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>
        [[nodiscard]] uint32_t take_for(const std::chrono::duration<Rep, Period>& timeout) noexcept {
            return _take(chrono::ticks(timeout));
        }
 
        template<typename Clock, typename Duration>
        [[nodiscard]] 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]] unsigned int priority() const noexcept;
 
        void set_priority(unsigned int 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;                            
        unsigned int priority = 5;                           
        std::optional<core_id> core_affinity = std::nullopt; 
        memory_type stack_mem = memory_type::internal;       
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit task(const config& cfg, std::move_only_function<void(self&)> task_func);
 
    [[nodiscard]] explicit task(const config& cfg, void (*task_func)(self&, void*), void* arg);
#endif
 
    [[nodiscard]] static result<std::unique_ptr<task>> make(config cfg, std::move_only_function<void(self&)> task_func);
 
    [[nodiscard]] static result<std::unique_ptr<task>> make(config cfg, void (*task_func)(self&, void*), void* arg);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static void spawn(config cfg, std::move_only_function<void(self&)> task_func) {
        unwrap(try_spawn(std::move(cfg), std::move(task_func)));
    }
 
    static void spawn(config cfg, void (*task_func)(self&, void*), void* arg) {
        unwrap(try_spawn(std::move(cfg), task_func, arg));
    }
#endif
 
    [[nodiscard]] static result<void> try_spawn(config cfg, std::move_only_function<void(self&)> task_func);
 
    [[nodiscard]] static result<void> try_spawn(config cfg, void (*task_func)(self&, void*), void* arg);
 
    ~task();
 
    // Non-copyable and non-movable
    task(const task&) = delete;
    task& operator=(const task&) = delete;
    task(task&&) = delete;
    task& operator=(task&&) = delete;
 
    [[nodiscard]] TaskHandle_t idf_handle() const noexcept { return _handle; }
 
    [[nodiscard]] const std::string& name() const noexcept { return _name; }
 
    [[nodiscard]] unsigned int 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(unsigned int new_priority) { unwrap(try_set_priority(new_priority)); }
#endif
 
    [[nodiscard]] result<void> try_set_priority(unsigned int 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);
 
    [[nodiscard]] static result<TaskHandle_t> _create(context* ctx, const config& cfg);
    [[nodiscard]] result<void> _try_join(TickType_t ticks);
 
    explicit task(TaskHandle_t handle, std::string name, context* ctx);
 
    TaskHandle_t _handle;
    std::string _name;
    context* _context;
};
 
 
} // namespace idfxx