executor.h

Go to the documentation of this file.

#pragma once

 
#include "fl/task/promise.h"
#include "fl/task/promise_result.h"
#include "fl/task/scheduler.h"
#include "fl/stl/singleton.h"
#include "fl/task/task.h"
#include "platforms/await.h"
#include "fl/stl/cstddef.h"     // for size_t
#include "fl/stl/stdint.h"      // for u8
#include "fl/stl/vector.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
namespace task {

enum class ExecFlags : u8 {
    TASKS      = 1 << 0,
    COROUTINES = 1 << 1,
    SYSTEM     = 1 << 2,
    ALL        = (1 << 0) | (1 << 1) | (1 << 2)
};
 
inline ExecFlags operator|(ExecFlags a, ExecFlags b) FL_NO_EXCEPT {
    return static_cast<ExecFlags>(static_cast<u8>(a) | static_cast<u8>(b));
}
 
inline bool operator&(ExecFlags a, ExecFlags b) FL_NO_EXCEPT {
    return (static_cast<u8>(a) & static_cast<u8>(b)) != 0;
}
 
namespace detail {
int& await_depth_tls() FL_NO_EXCEPT;
} // namespace detail

class Runner {
public:
    virtual ~Runner() FL_NO_EXCEPT = default;

    virtual void update() FL_NO_EXCEPT = 0;

    virtual bool has_active_tasks() const FL_NO_EXCEPT = 0;

    virtual size_t active_task_count() const FL_NO_EXCEPT = 0;
};

class Executor {
public:
    static Executor& instance() FL_NO_EXCEPT;

    void register_runner(Runner* r) FL_NO_EXCEPT;

    void unregister_runner(Runner* r) FL_NO_EXCEPT;

    void update_all() FL_NO_EXCEPT;

    bool has_active_tasks() const FL_NO_EXCEPT;

    size_t total_active_tasks() const FL_NO_EXCEPT;
 
private:
    fl::vector<Runner*> mRunners;
};

void run(fl::u32 microseconds = 1000, ExecFlags flags = ExecFlags::ALL) FL_NO_EXCEPT;

void yield_system(fl::u32 microseconds) FL_NO_EXCEPT;
 
 

size_t active_tasks() FL_NO_EXCEPT;

bool has_tasks() FL_NO_EXCEPT;

template<typename T>
PromiseResult<T> await_top_level(Promise<T> p) FL_NO_EXCEPT {
    // Handle invalid promises
    if (!p.valid()) {
        return PromiseResult<T>(Error("Invalid promise"));
    }
 
    // If already completed, return immediately
    if (p.is_completed()) {
        if (p.is_resolved()) {
            return PromiseResult<T>(p.value());
        } else {
            return PromiseResult<T>(p.error());
        }
    }
 
    // Track recursion depth to prevent infinite loops
    int& await_depth = detail::await_depth_tls();
    if (await_depth > 10) {
        return PromiseResult<T>(Error("await_top_level recursion limit exceeded - possible infinite loop"));
    }
 
    ++await_depth;
 
    // Wait for promise to complete while pumping async tasks
    int pump_count = 0;
    const int max_pump_iterations = 10000; // Safety limit
 
    while (!p.is_completed() && pump_count < max_pump_iterations) {
        // Update the promise first (in case it's not managed by async system)
        p.update();
 
        // Check if completed after update
        if (p.is_completed()) {
            break;
        }
 
        // Platform-agnostic async pump and yield
        run(1000);
 
        ++pump_count;
    }
 
    --await_depth;
 
    // Check for timeout
    if (pump_count >= max_pump_iterations) {
        return PromiseResult<T>(Error("await_top_level timeout - promise did not complete"));
    }
 
    // Return the result
    if (p.is_resolved()) {
        return PromiseResult<T>(p.value());
    } else {
        return PromiseResult<T>(p.error());
    }
}
 
} // namespace task
} // namespace fl
 
// ============================================================================
// Await API Comparison: await() vs await_top_level()
// ============================================================================
//
// FastLED provides two await functions for different contexts:
//
// 1. fl::task::await() - For coroutines (ESP32/Host only)
//    - Zero CPU overhead (true OS-level blocking)
//    - Must be called from fl::task::coroutine() context
//    - Suspends coroutine thread until promise completes
//    - Platform support: ESP32 (FreeRTOS), Host/Stub (std::thread)
//
// 2. fl::task::await_top_level() - For main loop/top-level code (All platforms)
//    - High CPU usage (busy-wait with run(1000))
//    - Safe to call from Arduino loop() or main()
//    - NOT safe in promise callbacks or nested async operations
//    - Platform support: All platforms
//
// **When to use which?**
// - In fl::task::coroutine(): Use fl::task::await() for zero CPU waste
// - In Arduino loop() or main(): Use fl::task::await_top_level()
// - Other platforms without coroutine support: Use fl::task::await_top_level()
//
// ============================================================================
 
 
 
namespace fl {
namespace task {

template<typename T>
inline PromiseResult<T> await(
    Promise<T> p,
    fl::u32 timeout_ms = fl::platforms::kAwaitDefaultTimeoutMs) FL_NO_EXCEPT {
    return fl::platforms::await(p, timeout_ms);
}
 
} // namespace task
} // namespace fl