engine::Future< T > Class Template Reference

Table of Contents

• Detailed Description
• Example usage:
• Public Member Functions
• Member Function Documentation
• get()
• valid()
• wait()
• wait_for()
• wait_until() [1/2]
• wait_until() [2/2]
• Friends And Related Symbol Documentation
• Promise< T >

#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.
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 189 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 184 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 195 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 202 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 215 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 209 of file future.hpp.

Friends And Related Symbol Documentation

Promise< T >

template<typename T >

friend class Promise< T >

friend

Definition at line 102 of file future.hpp.

---

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

• userver/engine/future.hpp