Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C++

std::future_status — the result of a timed wait

std::future_status is a scoped enumeration from <future>, returned by wait_for() and wait_until(). It distinguishes a ready result, an expired timeout, and deferred execution. The status itself neither retrieves the value nor tells you whether the computation completed without an exception.

Version: C++23; repository compiler flag, production runtime not attested

Syntax

#include <future>
// Declared in namespace std:
enum class future_status { ready, timeout, deferred };
// f.wait_for(duration) and f.wait_until(time_point) return std::future_status.

std::future_status is an enum class from <future>. The wait_for() and wait_until() members of std::future<T> and std::shared_future<T> return this type. The former takes a duration; the latter takes a time point. They check shared-state readiness rather than retrieve the result.

std::future_status::ready means the shared state holds a value or an exception ready for retrieval. It does not guarantee successful computation: get() can rethrow the stored exception. std::future_status::timeout means the wait returned because its timeout expired; it does not cancel the task or prove that the task is still running when you examine the status.

std::future_status::deferred means the state contains a deferred function, for example one created by std::async(std::launch::deferred, ...). A timed wait does not start it and returns this status without waiting for the timeout. The first non-timed wait, through wait() or get(), runs it in the calling thread. A loop that only polls wait_for() will not start such a task.

Call waiting members only on an object with a shared state: valid() does not mean ready. For std::future<T>, calling get() consumes the result and leaves valid() == false; subsequently waiting on that object has undefined behavior. The example deterministically checks all three statuses using wait_for(0ms), a promise, and an explicitly deferred task, without sleeping. The cited pages are a living working draft, not a frozen C++23 text.

Examples

#include <chrono>
#include <future>
#include <iostream>

int main() {
    using namespace std::chrono_literals;
    std::cout << std::boolalpha;

    std::promise<int> producer;
    auto result = producer.get_future();
    std::cout << "timeout: "
              << (result.wait_for(0ms) == std::future_status::timeout) << '\n';

    producer.set_value(42);
    std::cout << "ready: "
              << (result.wait_for(0ms) == std::future_status::ready) << '\n';

    auto lazy = std::async(std::launch::deferred, [] { return 7; });
    std::cout << "deferred: "
              << (lazy.wait_for(0ms) == std::future_status::deferred) << '\n';

    std::cout << "values: " << result.get() << ' ' << lazy.get() << '\n';
}

Result

timeout: true
ready: true
deferred: true
values: 42 7

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources