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:

unavailable: the computation has not been completed yet
value: the computation has been completed successfully and a value is available.
failed: the computation completed with an exception.

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.

A future should not be discarded before it is waited upon and its result is extracted. Discarding a future means that the computed value becomes inaccessible, but more importantly, any exceptions raised from the computation will disappear unchecked as well. Another very important consequence is potentially unbounded resource consumption due to the launcher of the deserted continuation not being able track the amount of in-progress continuations, nor their individual resource consumption. To prevent accidental discarding of futures, future is declared [[nodiscard]] if the compiler supports it. Also, when a discarded future resolves with an error a warning is logged (at runtime). That said there can be legitimate cases where a future is discarded. The most prominent example is launching a new fiber, or in other words, moving a continuation chain to the background (off the current fiber). Even if a future is discarded purposefully, it is still strongly advisable to wait on it indirectly (via a gate or semaphore), control their concurrency, their resource consumption and handle any errors raised from them.

Template Parameters

T A 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 = internal::future_stored_type_t< T >
	The data type carried by the future.

using	tuple_type = internal::future_tuple_type_t< value_type >

using	promise_type = promise< T >
	The data type carried by the future.

using	get0_return_type = typename future_state::get0_return_type

Public Member Functions
	future (future &&x) noexcept
	Moves the future into a new object.

	future (const future &)=delete

future &	operator= (future &&x) noexcept

void	operator= (const future &)=delete

value_type &&	get ()
	gets the value returned by the computation More...

std::exception_ptr	get_exception () noexcept

get0_return_type	get0 ()

void	wait () noexcept

bool	available () const noexcept
	Checks whether the future is available. More...

bool	failed () const noexcept
	Checks whether the future has failed. More...

template<typename Func , typename Result = typename internal::future_result<Func, T>::future_type>
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<internal::result_of_apply_t<Func, T>>>
Result	then_unpack (Func &&func) noexcept
	Schedule a block of code to run when the future is ready, unpacking tuples. More...

template<typename Func , typename FuncResult = std::invoke_result_t<Func, future>>
futurize_t< FuncResult >	then_wrapped (Func &&func) &noexcept
	Schedule a block of code to run when the future is ready, allowing for exception handling. More...

template<typename Func , typename FuncResult = std::invoke_result_t<Func, future&&>>
futurize_t< FuncResult >	then_wrapped (Func &&func) &&noexcept

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 Typedef Documentation

◆ get0_return_type

template<typename T >

using seastar::future< T >::get0_return_type = typename future_state::get0_return_type

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()).

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 ( ) const

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

pr	a promise that will be fulfilled with the results of this future.

◆ get()

template<typename T >

value_type&& 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.

◆ 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_type(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 = typename internal::future_result<Func, T>::future_type>

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_unpack()

template<typename T >

template<typename Func , typename Result = futurize_t<internal::result_of_apply_t<Func, T>>>

Result seastar::future< T >::then_unpack ( Func && func )

inlinenoexcept

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

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.

This member function is only available when the payload is std::tuple; The tuple elements are passed as individual arguments to func, which must have the same arity as the tuple.

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 FuncResult = std::invoke_result_t<Func, future>>

futurize_t<FuncResult> 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:

seastar/core/future.hh

Detailed Description

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

Classes

Public Types

Public Member Functions

Class Documentation

◆ seastar::future::finally_body

Member Typedef Documentation

◆ get0_return_type

Member Function Documentation

◆ available()

◆ discard_result()

◆ failed()

◆ finally()

◆ forward_to()

◆ get()

◆ handle_exception()

◆ handle_exception_type()

◆ ignore_ready_future()

◆ or_terminate()

◆ then()

◆ then_unpack()

◆ then_wrapped()

◆ wait()

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