userver: engine::Future< T > Class Template Reference
⚠️ This is the documentation for an old userver version. Click here to switch to the latest version.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
engine::Future< T > Class Template Referencefinal

#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;
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...
int_promise.set_value(kTestValue);
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) {
x = int_future.get();
ASSERT_EQ(x, kTestValue);
// ...
break;
// Timeout Handling
break;
// 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
 
Futureoperator= (const Future &)=delete
 
Futureoperator= (Future &&) noexcept=default
 
bool valid () const noexcept
 Returns whether this Future holds a valid state.
 
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
WaitInterruptedExceptionif the current task has been cancelled in the process.
std::future_errorif 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_errorif 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_errorif 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_errorif 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_errorif 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: