Seastar
High performance C++ framework for concurrent servers
Classes | Public Types | Public Member Functions | List of all members
seastar::future< T > Class Template Reference

Detailed Description

template<typename... T>
class seastar::future< T >

A representation of a possibly not-yet-computed value.

A future represents a value that has not yet been computed (an asynchronous computation). It can be in one of several states:

methods in future allow querying the state and, most importantly, scheduling a continuation to be executed when the future becomes available. Only one such continuation may be scheduled.

Template Parameters
TA list of types to be carried as the result of the future, similar to std::tuple<T...>. An empty list (future<>) means that there is no result, and an available future only contains a success/failure indication (and in the case of a failure, an exception). A list with two or more types is deprecated; use future<std::tuple<T...>> instead.

#include <seastar/core/future.hh>

Inheritance diagram for seastar::future< T >:

Classes

struct  finally_body
 
struct  finally_body< Func, false >
 
struct  finally_body< Func, true >
 

Public Types

using value_type = std::tuple< T... >
 The data type carried by the future.
 
using promise_type = promise< T... >
 The data type carried by the future.
 

Public Member Functions

 future (future &&x) noexcept
 Moves the future into a new object.
 
 future (const future &)=delete
 
futureoperator= (future &&x) noexcept
 
void operator= (const future &)=delete
 
std::tuple< T... > get ()
 gets the value returned by the computation More...
 
std::exception_ptr get_exception ()
 
future_state< T... >::get0_return_type get0 ()
 
void wait () noexcept
 
bool available () const noexcept
 Checks whether the future is available. More...
 
bool failed () noexcept
 Checks whether the future has failed. More...
 
template<typename Func , typename Result = futurize_t<std::result_of_t<Func(T&&...)>>>
Result then (Func &&func) noexcept
 Schedule a block of code to run when the future is ready. More...
 
template<typename Func , typename Result = futurize_t<std::result_of_t<Func(future)>>>
Result then_wrapped (Func &&func) noexcept
 Schedule a block of code to run when the future is ready, allowing for exception handling. More...
 
void forward_to (promise< T... > &&pr) noexcept
 Satisfy some promise object with this future as a result. More...
 
template<typename Func >
future< T... > finally (Func &&func) noexcept
 
future or_terminate () noexcept
 Terminate the program if this future fails. More...
 
future discard_result () noexcept
 Discards the value carried by this future. More...
 
template<typename Func >
future< T... > handle_exception (Func &&func) noexcept
 Handle the exception carried by this future. More...
 
template<typename Func >
future< T... > handle_exception_type (Func &&func) noexcept
 Handle the exception of a certain type carried by this future. More...
 
void ignore_ready_future () noexcept
 Ignore any result hold by this future. More...
 

Class Documentation

◆ seastar::future::finally_body

struct seastar::future::finally_body

Member Function Documentation

◆ available()

template<typename... T>
bool seastar::future< T >::available ( ) const
inlinenoexcept

Checks whether the future is available.

Returns
true if the future has a value, or has failed.

◆ discard_result()

template<typename... T>
future seastar::future< T >::discard_result ( )
inlinenoexcept

Discards the value carried by this future.

Converts the future into a no-value future<>, by ignoring any result. Exceptions are propagated unchanged.

◆ failed()

template<typename... T>
bool seastar::future< T >::failed ( )
inlinenoexcept

Checks whether the future has failed.

Returns
true if the future is availble and has failed.

◆ finally()

template<typename... T>
template<typename Func >
future<T...> seastar::future< T >::finally ( Func &&  func)
inlinenoexcept

Finally continuation for statements that require waiting for the result. I.e. you need to "finally" call a function that returns a possibly unavailable future. The returned future will be "waited for", any exception generated will be propagated, but the return value is ignored. I.e. the original return value (the future upon which you are making this call) will be preserved.

If the original return value or the callback return value is an exceptional future it will be propagated.

If both of them are exceptional - the std::nested_exception exception with the callback exception on top and the original future exception nested will be propagated.

◆ forward_to()

template<typename... T>
void seastar::future< T >::forward_to ( promise< T... > &&  pr)
inlinenoexcept

Satisfy some promise object with this future as a result.

Arranges so that when this future is resolve, it will be used to satisfy an unrelated promise. This is similar to scheduling a continuation that moves the result of this future into the promise (using promise::set_value() or promise::set_exception(), except that it is more efficient.

Parameters
pra promise that will be fulfilled with the results of this future.

◆ get()

template<typename... T>
std::tuple<T...> seastar::future< T >::get ( )
inline

gets the value returned by the computation

Requires that the future be available. If the value was computed successfully, it is returned (as an std::tuple). Otherwise, an exception is thrown.

If get() is called in a seastar::thread context, then it need not be available; instead, the thread will be paused until the future becomes available.

◆ get0()

template<typename... T>
future_state<T...>::get0_return_type seastar::future< T >::get0 ( )
inline

Gets the value returned by the computation.

Similar to get(), but instead of returning a tuple, returns the first value of the tuple. This is useful for the common case of a future<T> with exactly one type parameter.

Equivalent to: std::get<0>(f.get()).

◆ handle_exception()

template<typename... T>
template<typename Func >
future<T...> seastar::future< T >::handle_exception ( Func &&  func)
inlinenoexcept

Handle the exception carried by this future.

When the future resolves, if it resolves with an exception, handle_exception(func) replaces the exception with the value returned by func. The exception is passed (as a std::exception_ptr) as a parameter to func; func may return the replacement value immediately (T or std::tuple<T...>) or in the future (future<T...>) and is even allowed to return (or throw) its own exception.

The idiom fut.discard_result().handle_exception(...) can be used to handle an exception (if there is one) without caring about the successful value; Because handle_exception() is used here on a future<>, the handler function does not need to return anything.

◆ handle_exception_type()

template<typename... T>
template<typename Func >
future<T...> seastar::future< T >::handle_exception_type ( Func &&  func)
inlinenoexcept

Handle the exception of a certain type carried by this future.

When the future resolves, if it resolves with an exception of a type that provided callback receives as a parameter, handle_exception(func) replaces the exception with the value returned by func. The exception is passed (by reference) as a parameter to func; func may return the replacement value immediately (T or std::tuple<T...>) or in the future (future<T...>) and is even allowed to return (or throw) its own exception. If exception, that future holds, does not match func parameter type it is propagated as is.

◆ ignore_ready_future()

template<typename... T>
void seastar::future< T >::ignore_ready_future ( )
inlinenoexcept

Ignore any result hold by this future.

Ignore any result (value or exception) hold by this future. Use with caution since usually ignoring exception is not what you want

◆ or_terminate()

template<typename... T>
future seastar::future< T >::or_terminate ( )
inlinenoexcept

Terminate the program if this future fails.

Terminates the entire program is this future resolves to an exception. Use with caution.

◆ then()

template<typename... T>
template<typename Func , typename Result = futurize_t<std::result_of_t<Func(T&&...)>>>
Result seastar::future< T >::then ( Func &&  func)
inlinenoexcept

Schedule a block of code to run when the future is ready.

Schedules a function (often a lambda) to run when the future becomes available. The function is called with the result of this future's computation as parameters. The return value of the function becomes the return value of then(), itself as a future; this allows then() calls to be chained.

If the future failed, the function is not called, and the exception is propagated into the return value of then().

Parameters
func- function to be called when the future becomes available, unless it has failed.
Returns
a future representing the return value of func, applied to the eventual value of this future.

◆ then_wrapped()

template<typename... T>
template<typename Func , typename Result = futurize_t<std::result_of_t<Func(future)>>>
Result seastar::future< T >::then_wrapped ( Func &&  func)
inlinenoexcept

Schedule a block of code to run when the future is ready, allowing for exception handling.

Schedules a function (often a lambda) to run when the future becomes available. The function is called with the this future as a parameter; it will be in an available state. The return value of the function becomes the return value of then_wrapped(), itself as a future; this allows then_wrapped() calls to be chained.

Unlike then(), the function will be called for both value and exceptional futures.

Parameters
func- function to be called when the future becomes available,
Returns
a future representing the return value of func, applied to the eventual value of this future.

◆ wait()

template<typename... T>
void seastar::future< T >::wait ( )
inlinenoexcept

Wait for the future to be available (in a seastar::thread)

When called from a seastar::thread, this function blocks the thread until the future is availble. Other threads and continuations continue to execute; only the thread is blocked.


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