await_top_level()

template<typename T>

PromiseResult< T > fl::task::await_top_level

(

Promise< T >

p

)

Synchronously wait for a promise to complete (ONLY safe in top-level contexts)

Template Parameters

T	The type of value the promise resolves to (automatically deduced)

Parameters

p	The promise to wait for

Returns

A promise_result containing either the resolved value T or an Error

This function blocks until the promise is either resolved or rejected, then returns a promise_result that can be checked with ok() for success/failure. While waiting, it continuously calls run(1000) to pump async tasks and yield appropriately.

PERFORMANCE NOTE: This function busy-waits (high CPU usage) while the promise is pending. For coroutines on ESP32 or Host/Stub platforms, prefer fl::task::await() which truly blocks the coroutine with zero CPU overhead.

SAFETY WARNING: This function should ONLY be called from top-level contexts like Arduino loop() function. Never call this from:

• Promise callbacks (.then, .catch_)
• Nested async operations
• Interrupt handlers
• Library initialization code
• Coroutine contexts (use fl::task::await() instead)

The "_top_level" suffix emphasizes this safety requirement.

Examples

auto p = fl::fetch_get("http://example.com");
auto result = fl::task::await_top_level(p);  // Type automatically deduced!
 
if (result.ok()) {
    const Response& resp = result.value();
    FL_WARN("Success: " << resp.text());
} else {
    FL_WARN("Error: " << result.error().message);
}

Definition at line 186 of file executor.h.

                                               {
    // 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());
    }
}

References fl::task::detail::await_depth_tls(), fl::Error, fl::task::Promise< T >::error(), fl::task::Promise< T >::is_completed(), fl::task::Promise< T >::is_resolved(), run(), fl::task::Promise< T >::update(), fl::task::Promise< T >::valid(), and fl::task::Promise< T >::value().

Referenced by test_await_approach(), test_get_endpoint(), test_json_await(), test_json_endpoint(), and test_ping_endpoint().

Here is the call graph for this function:

Here is the caller graph for this function: