Seastar
High performance C++ framework for concurrent servers
Namespaces | Classes | Functions
Futures and Promises

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. More...

Namespaces

 seastar
 Seastar API namespace.
 

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...
 
class  seastar::promise< void >
 Specialization of promise<void> 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)
 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, typename Exception >
future< T... > seastar::make_exception_future (Exception &&ex) noexcept
 Creates a future in an available, failed state. More...
 
future< T... > seastar::promise< T >::get_future () noexcept
 Gets the promise's associated future. More...
 

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.


Class Documentation

◆ seastar::with_clock

struct seastar::with_clock

template<typename Clock>
struct seastar::with_clock< Clock >

Changes the clock used by shared_future<> and shared_promise<> when passed as the first template parameter.

Function Documentation

◆ 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>
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_exception_future() [2/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_ready_future()

template<typename... T, typename... A>
future< T... > seastar::make_ready_future ( A &&...  value)
inline

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