Seastar
High performance C++ framework for concurrent servers
Modules | Classes | Functions
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, typename... A>
future< T... > seastar::make_ready_future (A &&... value) noexcept
 Creates a future in an available, value state. More...
 
template<typename... T>
future< T... > seastar::make_exception_future (std::exception_ptr &&value) noexcept
 Creates a future in an available, failed state. More...
 
template<typename... T>
future< T... > seastar::make_exception_future (const std::exception_ptr &ex) noexcept
 
template<typename... T>
future< T... > seastar::make_exception_future (std::exception_ptr &ex) noexcept
 
template<typename... T>
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 (Exception &&ex) noexcept
 Creates a future in an available, failed state. More...
 
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>
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, 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>
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, 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).