await_top_level()

template<typename T>

fl::result< T > fl::await_top_level

(

fl::promise< T >

promise

)

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

promise

The promise to wait for

Returns

A PromiseResult containing either the resolved value T or an Error

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

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

The "_top_level" suffix emphasizes this safety requirement.

Type Deduction: The template parameter T is automatically deduced from the promise parameter, so you don't need to specify it explicitly.

Usage

auto promise = fl::fetch_get("http://example.com");
auto result = fl::await_top_level(promise);  // Type automatically deduced!
 
if (result.ok()) {
    const Response& resp = result.value();
    FL_WARN("Success: " << resp.text());
} else {
    FL_WARN("Error: " << result.error().message);
}
 
// Or use operator bool
if (result) {
    FL_WARN("Got response: " << result.value().status());
}
 
// You can still specify the type explicitly if needed:
auto explicit_result = fl::await_top_level<response>(promise);

Definition at line 175 of file async.h.

                                                  {
    // Handle invalid promises
    if (!promise.valid()) {
        return fl::result<T>(Error("Invalid promise"));
    }
    
    // If already completed, return immediately
    if (promise.is_completed()) {
        if (promise.is_resolved()) {
            return fl::result<T>(promise.value());
        } else {
            return fl::result<T>(promise.error());
        }
    }
    
    // Track recursion depth to prevent infinite loops
    static fl::ThreadLocal<int> await_depth(0);
    if (await_depth.access() > 10) {
        return fl::result<T>(Error("await_top_level recursion limit exceeded - possible infinite loop"));
    }
    
    ++await_depth.access();
    
    // Wait for promise to complete while pumping async tasks
    int pump_count = 0;
    const int max_pump_iterations = 10000; // Safety limit
    
    while (!promise.is_completed() && pump_count < max_pump_iterations) {
        // Update the promise first (in case it's not managed by async system)
        promise.update();
        
        // Check if completed after update
        if (promise.is_completed()) {
            break;
        }
        
        // Platform-agnostic async pump and yield
        async_yield();
        
        ++pump_count;
    }
    
    --await_depth.access();
    
    // Check for timeout
    if (pump_count >= max_pump_iterations) {
        return fl::result<T>(Error("await_top_level timeout - promise did not complete"));
    }
    
    // Return the result
    if (promise.is_resolved()) {
        return fl::result<T>(promise.value());
    } else {
        return fl::result<T>(promise.error());
    }
}

References fl::ThreadLocalFake< T >::access(), async_yield(), fl::promise< T >::error(), fl::promise< T >::is_completed(), fl::promise< T >::is_resolved(), fl::promise< T >::update(), fl::promise< T >::valid(), and fl::promise< T >::value().

Referenced by test_await_approach(), and test_json_await().

Here is the call graph for this function:

Here is the caller graph for this function: