std::shared...e::wait_for(3)

✨ std::shared...e::wait_for(3) ✨

okay so bestie, this one is straight out of the C++ Standard Libary and it's literally the std::shared_future version of "wait for it… but with a timer." 💅

🌸 NAME 🌸

std::shared_future::wait_for — yes king, that's the name, that's the function 🫶

🦋 Synopsis 🦋

template< class Rep, class Period >
std::future_status wait_for( const std::chrono::duration<Rep,Period>&
(since C++11)
timeout_duration ) const;

She waits for the result to become available, no cap. Blocks until the specified timeout_duration has elapsed or the result becomes available — whichever comes first. The return value identifies the state of the result, iykyk. 💖

If the future is the result of a call to std::async that used lazy evaluation, this function returns immediately without waiting. Not her waiting around, she's got stuff to do. ✨

Heads up bestie: this function may block for longer than timeout_duration due to scheduling or resource contention delays. She's doing her best 😭

The standard recommends that a steady clock is used to measure the duration. If an implementation uses a system clock instead, the wait time may also be sensitive to clock adjustments. Clock behavior said "it's giving main character energy" and honestly? Fair. 🕰️

🚨 DANGER, BESTIE 🚨 The behavior is undefined if valid() is false before the call to this function. Like, undefined undefined. Do not play with that. 💀

🎀 Parameters 🎀

• timeout_duration — maximum duration to block for. That's the whole vibe. ⏳

👑 Return value 👑

• future_status::deferred — The shared state contains a deferred function using lazy evaluation, so the result will be computed only when explicitly requested. She's not ready yet, she's thinking. 🙈
• future_status::ready — The result is ready. Slay! 🎉
• future_status::timeout — The timeout has expired. Time's up, babe. ⌛

🍓 Exceptions 🍓

Any exception thrown by clock, time_point, or duration during the execution. And before you panic: clocks, time points, and durations provided by the standard library never throw. So that's a little comfort. 🫶

🌈 Notes 🌈

The implementations are encouraged to detect the case when valid == false before the call and throw a std::future_error with an error condition of std::future_errc::no_state. Like, please catch that mess early. 💅

🧚 Example 🧚

#include <chrono>
#include <future>
#include <iostream>
#include <thread>
using namespace std::chrono_literals;

int main()
{
    std::shared_future<int> future = std::async(std::launch::async, []()
    {
        std::this_thread::sleep_for(3s);
        return 8;
    });

    std::cout << "waiting...\n";
    std::future_status status;

    do
    {
        switch (status = future.wait_for(1s); status)
        {
            case std::future_status::deferred:
                std::cout << "deferred\n";
                break;
            case std::future_status::timeout:
                std::cout << "timeout\n";
                break;
            case std::future_status::ready:
                std::cout << "ready!\n";
                break;
        }
    }
    while (status != std::future_status::ready);

    std::cout << "result is " << future.get() << '\n';
}

⭐ Possible output ⭐

waiting...
timeout
timeout
timeout
ready!
result is 8

💜 See also 💜

• wait — waits for the result to become available (public member function)
• wait_until — waits for the result, returns if it is not available until specified time point has been reached (public member function)

---

okay that's the whole page, bestie, we ate and left no crumbs. 🍽️✨ This iconic little manual page is from http://cppreference.com, dated 2024.06.10, and its title is literally std::shared...e::wait_for(3). Periodt. 💅🎀