engine::Future< T > Class Template Reference

#include <userver/engine/future.hpp>

Detailed Description

template<typename T>
class engine::Future< T >

std::future replacement for asynchronous tasks that works in pair with engine::Promise

engine::Future can only be used from coroutine threads.

Example usage:

    engine::Promise<int> int_promise;
    engine::Promise<std::string> string_promise;
    auto deadline = GetDeadline();
 
    constexpr auto kBadValue = -1;
    constexpr auto kFallbackString = "Bad string";
 
    constexpr auto kTestValue = 777;
    constexpr auto kTestString = "Test string value";
 
    auto int_future = int_promise.get_future();
    auto string_future = string_promise.get_future();
 
    auto calc_task = utils::Async(
        "calc",
        [int_promise = std::move(int_promise), string_promise = std::move(string_promise), kTestValue]() mutable {
            // Emulating long calculation of x and s...
            engine::SleepFor(100ms);
            int_promise.set_value(kTestValue);
 
            engine::SleepFor(100ms);
            string_promise.set_value(kTestString);
            // Other calculations.
        }
    );
 
    auto int_consumer =
        utils::Async("int_consumer", [deadline, int_future = std::move(int_future), kTestValue]() mutable {
            auto status = int_future.wait_until(deadline);
            auto x = kBadValue;
            switch (status) {
                case engine::FutureStatus::kReady:
                    x = int_future.get();
                    ASSERT_EQ(x, kTestValue);
                    // ...
                    break;
                case engine::FutureStatus::kTimeout:
                    // Timeout Handling
                    break;
                case engine::FutureStatus::kCancelled:
                    // Handling cancellation of calculations
                    // (example, return to queue)
                    return;
            }
        });
 
    auto string_consumer =
        utils::Async("string_consumer", [string_future = std::move(string_future), kTestString]() mutable {
            std::string s;
            try {
                s = string_future.get();
                ASSERT_EQ(s, kTestString);
            } catch (const std::exception& ex) {
                // Exception Handling
                s = kFallbackString;
            }
            // ...
        });
 
    calc_task.Get();
    int_consumer.Get();
    string_consumer.Get();

See also

Synchronization Primitives

Definition at line 51 of file future.hpp.

Public Member Functions
	Future ()=default
	Creates an Future without a valid state.
	Future (const Future &)=delete
	Future (Future &&) noexcept=default
Future &	operator= (const Future &)=delete
Future &	operator= (Future &&) noexcept=default
bool	valid () const noexcept
	Returns whether this Future holds a valid state.
bool	is_ready () const
	Returns whether the value is available.
T	get ()
	Waits for value availability and retrieves it.
FutureStatus	wait () const
	Waits for value availability.
template<typename Rep , typename Period >
FutureStatus	wait_for (std::chrono::duration< Rep, Period > timeout) const
	Waits for value availability until the timeout expires or until the task is cancelled.
template<typename Clock , typename Duration >
FutureStatus	wait_until (std::chrono::time_point< Clock, Duration > until) const
	Waits for value availability until the deadline is reached or until the task is cancelled.
FutureStatus	wait_until (Deadline deadline) const
	Waits for value availability until the deadline is reached or until the task is cancelled.

Member Function Documentation

get()

template<typename T >

T engine::Future< T >::get

(

)

Waits for value availability and retrieves it.

Exceptions

WaitInterruptedException	if the current task has been cancelled in the process.
std::future_error	if Future holds no state, if the Promise has been destroyed without setting a value or if the value has already been retrieved.

Definition at line 202 of file future.hpp.

is_ready()

template<typename T >

bool engine::Future< T >::is_ready

(

)

const

Returns whether the value is available.

Warning

If value is set and task is being canceled or if Promise has been destroyed without setting a value, returns true.

Exceptions

std::future_error

if Future holds no state or if the value has already been retrieved.

Definition at line 196 of file future.hpp.

valid()

template<typename T >

bool engine::Future< T >::valid ( ) const

noexcept

Returns whether this Future holds a valid state.

Definition at line 191 of file future.hpp.

wait()

template<typename T >

FutureStatus engine::Future< T >::wait

(

)

const

Waits for value availability.

Returns

FutureStatus::kReady if the value is available.

FutureStatus::kCancelled if current task is being cancelled.

Exceptions

std::future_error

if Future holds no state.

Definition at line 208 of file future.hpp.

wait_for()

template<typename T >

template<typename Rep , typename Period >

FutureStatus engine::Future< T >::wait_for

(

std::chrono::duration< Rep, Period >

timeout

)

const

Waits for value availability until the timeout expires or until the task is cancelled.

Returns

FutureStatus::kReady if the value is available.

FutureStatus::kTimeout if timeout has expired.

FutureStatus::kCancelled if current task is being cancelled.

Exceptions

std::future_error

if Future holds no state.

Definition at line 215 of file future.hpp.

wait_until() [1/2]

template<typename T >

FutureStatus engine::Future< T >::wait_until

(

Deadline

deadline

)

const

Waits for value availability until the deadline is reached or until the task is cancelled.

Returns

FutureStatus::kReady if the value is available.

FutureStatus::kTimeout if deadline was reached.

FutureStatus::kCancelled if current task is being cancelled.

Exceptions

std::future_error

if Future holds no state.

Definition at line 226 of file future.hpp.

wait_until() [2/2]

template<typename T >

template<typename Clock , typename Duration >

FutureStatus engine::Future< T >::wait_until

(

std::chrono::time_point< Clock, Duration >

until

)

const

Waits for value availability until the deadline is reached or until the task is cancelled.

Returns

FutureStatus::kReady if the value is available.

FutureStatus::kTimeout if until time point was reached.

FutureStatus::kCancelled if current task is being cancelled.

Exceptions

std::future_error

if Future holds no state.

Definition at line 221 of file future.hpp.

Friends And Related Symbol Documentation

Promise< T >

template<typename T >

friend class Promise< T >

friend

Definition at line 109 of file future.hpp.

---

The documentation for this class was generated from the following file:

• userver/engine/future.hpp