Futures and Promises

Detailed Description

Futures and promises are the basic tools for asynchronous programming in seastar. A future represents a result that may not have been computed yet, for example a buffer that is being read from the disk, or the result of a function that is executed on another cpu. A promise object allows the future to be eventually resolved by assigning it a value.

Another way to look at futures and promises are as the reader and writer sides, respectively, of a single-item, single use queue. You read from the future, and write to the promise, and the system takes care that it works no matter what the order of operations is.

The normal way of working with futures is to chain continuations to them. A continuation is a block of code (usually a lamdba) that is called when the future is assigned a value (the future is resolved); the continuation can then access the actual value.

Modules
	Implementation overview
	Future Utilities
	These utilities are provided to help perform operations on futures.

Classes
class	seastar::promise< T >
	promise - allows a future value to be made available at a later time. More...
class	seastar::future< T >
	A representation of a possibly not-yet-computed value. More...
class	seastar::shared_future< T >
	Like future except the result can be waited for by many fibers. More...
struct	seastar::broken_promise
	Exception type for broken promises. More...
struct	seastar::future_state_base
struct	seastar::ready_future_marker
struct	seastar::exception_future_marker
struct	seastar::future_for_get_promise_marker
struct	seastar::futurize< T >
	Converts a type to a future type, if it isn't already. More...
struct	seastar::with_clock< Clock >
	Changes the clock used by shared_future<> and shared_promise<> when passed as the first template parameter. More...
class	seastar::shared_promise< T >
	Like promise except that its counterpart is shared_future instead of future. More...

Functions
template<typename T = void, typename... A>
future< T >	seastar::make_ready_future (A &&... value) noexcept
	Creates a future in an available, value state. More...
template<typename T = void>
future< T >	seastar::make_exception_future (std::exception_ptr &&value) noexcept
	Creates a future in an available, failed state. More...
template<typename T = void, typename Exception >
future< T >	seastar::make_exception_future (Exception &&ex) noexcept
	Creates a future in an available, failed state. More...
template<typename T = void>
future< T >	seastar::make_exception_future (const std::exception_ptr &ex) noexcept
template<typename T = void>
future< T >	seastar::make_exception_future (std::exception_ptr &ex) noexcept
template<typename T = void>
future< T >	seastar::make_exception_future (const std::exception_ptr &&ex) noexcept
template<typename T = void>
future< T >	seastar::current_exception_as_future () noexcept
	Returns std::current_exception() wrapped in a future. More...
void	seastar::report_failed_future (future_state_base::any &&state) noexcept
void	seastar::log_exception_trace () noexcept
template<typename T , typename Exception >
future< T >	seastar::make_exception_future_with_backtrace (Exception &&ex) noexcept
void	seastar::future_state_base::any::check_failure () noexcept
future< T >	seastar::promise< T >::get_future () noexcept
	Gets the promise's associated future. More...
void	seastar::promise< T >::move_it (promise &&x) noexcept
	Moves a promise object.

---

Class Documentation

seastar::ready_future_marker

struct seastar::ready_future_marker

seastar::exception_future_marker

struct seastar::exception_future_marker

seastar::future_for_get_promise_marker

struct seastar::future_for_get_promise_marker

seastar::with_clock

struct seastar::with_clock

Function Documentation

current_exception_as_future()

template<typename T = void>

future< T > seastar::current_exception_as_future ( )

noexcept

Returns std::current_exception() wrapped in a future.

This is equivalent to make_exception_future(std::current_exception()), but expands to less code.

get_future()

template<typename T >

future< T > seastar::promise< T >::get_future

inlinenoexcept

Gets the promise's associated future.

The future and promise will be remember each other, even if either or both are moved. When set_value() or set_exception() are called on the promise, the future will be become ready, and if a continuation was attached to the future, it will run.

make_exception_future() [1/2]

template<typename T = void, typename Exception >

future< T > seastar::make_exception_future ( Exception &&  ex )

inlinenoexcept

Creates a future in an available, failed state.

Creates a future object that is already resolved in a failed state. This no I/O needs to be performed to perform a computation (for example, because the connection is closed and we cannot read from it).

make_exception_future() [2/2]

template<typename T = void>

future< T > seastar::make_exception_future ( std::exception_ptr &&  value )

inlinenoexcept

Creates a future in an available, failed state.

Creates a future object that is already resolved in a failed state. This is useful when no I/O needs to be performed to perform a computation (for example, because the connection is closed and we cannot read from it).

make_ready_future()

template<typename T = void, typename... A>

future< T > seastar::make_ready_future ( A &&...  value )

inlinenoexcept

Creates a future in an available, value state.

Creates a future object that is already resolved. This is useful when it is determined that no I/O needs to be performed to perform a computation (for example, because the data is cached in some buffer).