Seastar
High performance C++ framework for concurrent servers
Classes | Typedefs | Enumerations | Functions
Future Utilities

These utilities are provided to help perform operations on futures. More...

Classes

struct  seastar::stop_iteration_tag
 
struct  seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >
 Type helper for repeat_until_value() More...
 
struct  seastar::reducer_with_get_traits< T, IsFuture >
 
struct  seastar::reducer_with_get_traits< T, false >
 
struct  seastar::reducer_with_get_traits< T, true >
 
struct  seastar::reducer_traits< T, V >
 
struct  seastar::reducer_traits< T, decltype(std::declval< T >().get(), void())>
 
class  seastar::adder< Result, Addend >
 
class  seastar::timed_out_error
 
struct  seastar::default_timeout_exception_factory
 
struct  seastar::internal::future_has_value< Future >
 
struct  seastar::internal::tuple_to_future< Tuple >
 
struct  seastar::internal::tuple_to_future< std::tuple< Elements... > >
 
class  seastar::internal::extract_values_from_futures_tuple< Futures >
 
struct  seastar::internal::extract_values_from_futures_vector< Future >
 
struct  seastar::internal::extract_values_from_futures_vector< future<> >
 
struct  seastar::is_future< T >
 Check whether a type is a future. More...
 
struct  seastar::futurize< T >
 Converts a type to a future type, if it isn't already. More...
 

Typedefs

using seastar::stop_iteration = bool_class< stop_iteration_tag >
 
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::value_type = T
 The type of the value we are computing.
 
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::optional_type = std::experimental::optional< T >
 Type used by AsyncAction while looping.
 
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::future_type = future< value_type >
 Return type of repeat_until_value()
 
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::future_optional_type = future< optional_type >
 Return type of AsyncAction.
 
template<typename AsyncAction >
using seastar::repeat_until_value_return_type = typename repeat_until_value_type_helper< std::result_of_t< AsyncAction()> >::future_type
 Return value of repeat_until_value()
 
using seastar::reducer_with_get_traits< T, false >::result_type = decltype(std::declval< T >().get())
 
using seastar::reducer_with_get_traits< T, false >::future_type = future< result_type >
 
using seastar::reducer_with_get_traits< T, true >::future_type = decltype(std::declval< T >().get())
 
using seastar::reducer_traits< T, V >::future_type = future<>
 
using seastar::internal::tuple_to_future< std::tuple< Elements... > >::type = future< Elements... >
 
using seastar::internal::tuple_to_future< std::tuple< Elements... > >::promise_type = promise< Elements... >
 
using seastar::internal::extract_values_from_futures_tuple< Futures >::future_type = decltype(transform(std::declval< std::tuple< Futures... > >()))
 
using seastar::internal::extract_values_from_futures_tuple< Futures >::promise_type = typename future_type::promise_type
 
using seastar::internal::extract_values_from_futures_vector< Future >::value_type = decltype(untuple(std::declval< typename Future::value_type >()))
 
using seastar::internal::extract_values_from_futures_vector< Future >::future_type = future< std::vector< value_type > >
 
using seastar::internal::extract_values_from_futures_vector< future<> >::future_type = future<>
 
template<typename T >
using seastar::futurize_t = typename futurize< T >::type
 

Enumerations

enum  
 

Functions

template<typename T , typename F >
auto seastar::do_with (T &&rvalue, F &&f)
 
template<typename Lock , typename Func >
auto seastar::with_lock (Lock &lock, Func &&func)
 
template<typename T1 , typename T2 , typename T3_or_F , typename... More>
auto seastar::do_with (T1 &&rv1, T2 &&rv2, T3_or_F &&rv3, More &&... more)
 
template<typename Func , typename... Args>
auto seastar::with_scheduling_group (scheduling_group sg, Func func, Args &&... args)
 run a callable (with some arbitrary arguments) in a scheduling group More...
 
template<typename Iterator , typename Func >
future seastar::parallel_for_each (Iterator begin, Iterator end, Func &&func)
 
template<typename Range , typename Func >
future seastar::parallel_for_each (Range &&range, Func &&func)
 
template<typename AsyncAction >
future seastar::repeat (AsyncAction &&action)
 
template<typename AsyncAction >
repeat_until_value_return_type< AsyncAction > seastar::repeat_until_value (AsyncAction &&action)
 
template<typename AsyncAction , typename StopCondition >
future seastar::do_until (StopCondition stop_cond, AsyncAction action)
 
template<typename AsyncAction >
future seastar::keep_doing (AsyncAction &&action)
 
template<typename Iterator , typename AsyncAction >
future seastar::do_for_each (Iterator begin, Iterator end, AsyncAction &&action)
 
template<typename Container , typename AsyncAction >
future seastar::do_for_each (Container &c, AsyncAction &&action)
 
template<typename... Futs>
future< std::tuple< Futs... > > seastar::when_all (Futs &&... futs)
 
template<typename FutureIterator >
future< std::vector< typename std::iterator_traits< FutureIterator >::value_type > > seastar::when_all (FutureIterator begin, FutureIterator end)
 
static future_type seastar::reducer_with_get_traits< T, false >::maybe_call_get (future<> f, lw_shared_ptr< T > r)
 
static future_type seastar::reducer_with_get_traits< T, true >::maybe_call_get (future<> f, lw_shared_ptr< T > r)
 
static future_type seastar::reducer_traits< T, V >::maybe_call_get (future<> f, lw_shared_ptr< T > r)
 
template<typename Iterator , typename Mapper , typename Reducer >
auto seastar::map_reduce (Iterator begin, Iterator end, Mapper &&mapper, Reducer &&r) -> typename reducer_traits< Reducer >::future_type
 
template<typename Iterator , typename Mapper , typename Initial , typename Reduce >
future< Initial > seastar::map_reduce (Iterator begin, Iterator end, Mapper &&mapper, Initial initial, Reduce reduce)
 
template<typename Range , typename Mapper , typename Initial , typename Reduce >
future< Initial > seastar::map_reduce (Range &&range, Mapper &&mapper, Initial initial, Reduce reduce)
 
future seastar::adder< Result, Addend >::operator() (const Addend &value)
 
Result seastar::adder< Result, Addend >::get () &&
 
future seastar::now ()
 
future seastar::later ()
 
virtual const char * seastar::timed_out_error::what () const noexcept
 
static auto seastar::default_timeout_exception_factory::timeout ()
 
template<typename ExceptionFactory = default_timeout_exception_factory, typename Clock , typename Duration , typename... T>
future< T... > seastar::with_timeout (std::chrono::time_point< Clock, Duration > timeout, future< T... > f)
 Wait for either a future, or a timeout, whichever comes first. More...
 
static auto seastar::internal::tuple_to_future< std::tuple< Elements... > >::make_ready (std::tuple< Elements... > t)
 
static auto seastar::internal::tuple_to_future< std::tuple< Elements... > >::make_failed (std::exception_ptr excp)
 
static void seastar::internal::extract_values_from_futures_tuple< Futures >::set_promise (promise_type &p, std::tuple< Futures... > tuple)
 
static future_type seastar::internal::extract_values_from_futures_vector< Future >::run (std::vector< Future > futures)
 
static future_type seastar::internal::extract_values_from_futures_vector< future<> >::run (std::vector< future<>> futures)
 
template<typename... Futures>
auto seastar::when_all_succeed (Futures &&... futures)
 
template<typename FutureIterator , typename = typename std::iterator_traits<FutureIterator>::value_type>
auto seastar::when_all_succeed (FutureIterator begin, FutureIterator end)
 

Detailed Description

These utilities are provided to help perform operations on futures.


Class Documentation

◆ seastar::stop_iteration_tag

struct seastar::stop_iteration_tag

◆ seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >

struct seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >

template<typename T>
struct seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >

Type helper for repeat_until_value()

Class Members
typedef future< optional_type > future_optional_type Return type of AsyncAction.
typedef future< value_type > future_type Return type of repeat_until_value()
typedef optional< T > optional_type Type used by AsyncAction while looping.
typedef T value_type The type of the value we are computing.

◆ seastar::reducer_with_get_traits

struct seastar::reducer_with_get_traits

template<typename T, bool IsFuture>
struct seastar::reducer_with_get_traits< T, IsFuture >

◆ seastar::internal::tuple_to_future

struct seastar::internal::tuple_to_future

template<typename Tuple>
struct seastar::internal::tuple_to_future< Tuple >

Typedef Documentation

◆ future_optional_type

template<typename T >
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::future_optional_type = future<optional_type>

Return type of AsyncAction.

◆ future_type

template<typename T >
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::future_type = future<value_type>

Return type of repeat_until_value()

◆ optional_type

template<typename T >
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::optional_type = std::experimental::optional<T>

Type used by AsyncAction while looping.

◆ value_type

template<typename T >
using seastar::repeat_until_value_type_helper< future< std::experimental::optional< T > > >::value_type = T

The type of the value we are computing.

Function Documentation

◆ do_for_each() [1/2]

template<typename Iterator , typename AsyncAction >
future seastar::do_for_each ( Iterator  begin,
Iterator  end,
AsyncAction &&  action 
)
inline

Call a function for each item in a range, sequentially (iterator version).

For each item in a range, call a function, waiting for the previous invocation to complete before calling the next one.

Parameters
beginan InputIterator designating the beginning of the range
endan InputIterator designating the endof the range
actiona callable, taking a reference to objects from the range as a parameter, and returning a future<> that resolves when it is acceptable to process the next item.
Returns
a ready future on success, or the first failed future if action failed.

◆ do_for_each() [2/2]

template<typename Container , typename AsyncAction >
future seastar::do_for_each ( Container &  c,
AsyncAction &&  action 
)
inline

Call a function for each item in a range, sequentially (range version).

For each item in a range, call a function, waiting for the previous invocation to complete before calling the next one.

Parameters
rangean Range object designating input values
actiona callable, taking a reference to objects from the range as a parameter, and returning a future<> that resolves when it is acceptable to process the next item.
Returns
a ready future on success, or the first failed future if action failed.

◆ do_until()

template<typename AsyncAction , typename StopCondition >
future seastar::do_until ( StopCondition  stop_cond,
AsyncAction  action 
)
inline

Invokes given action until it fails or given condition evaluates to true.

Parameters
stop_conda callable taking no arguments, returning a boolean that evalutes to true when you don't want to call action any longer
actiona callable taking no arguments, returning a future<>. Will be called again as soon as the future resolves, unless the future fails, or stop_cond returns true.
Returns
a ready future if we stopped successfully, or a failed future if a call to to action failed.

◆ do_with() [1/2]

template<typename T , typename F >
auto seastar::do_with ( T &&  rvalue,
F &&  f 
)
inline

do_with() holds an object alive for the duration until a future completes, and allow the code involved in making the future complete to have easy access to this object.

do_with() takes two arguments: The first is an temporary object (rvalue), the second is a function returning a future (a so-called "promise"). The function is given (a moved copy of) this temporary object, by reference, and it is ensured that the object will not be destructed until the completion of the future returned by the function.

do_with() returns a future which resolves to whatever value the given future (returned by the given function) resolves to. This returned value must not contain references to the temporary object, as at that point the temporary is destructed.

Parameters
rvaluea temporary value to protect while f is running
fa callable, accepting an lvalue reference of the same type as rvalue, that will be accessible while f runs
Returns
whatever f returns

◆ do_with() [2/2]

template<typename T1 , typename T2 , typename T3_or_F , typename... More>
auto seastar::do_with ( T1 &&  rv1,
T2 &&  rv2,
T3_or_F &&  rv3,
More &&...  more 
)
inline

Multiple argument variant of do_with(T&& rvalue, F&& f).

This is the same as do_with(T&& tvalue, F&& f), but accepts two or more rvalue parameters, which are held in memory while f executes. f will be called with all arguments as reference parameters.

◆ keep_doing()

template<typename AsyncAction >
future seastar::keep_doing ( AsyncAction &&  action)
inline

Invoke given action until it fails.

Calls action repeatedly until it returns a failed future.

Parameters
actiona callable taking no arguments, returning a future<> that becomes ready when you wish it to be called again.
Returns
a future<> that will resolve to the first failure of action

◆ map_reduce() [1/2]

template<typename Iterator , typename Mapper , typename Initial , typename Reduce >
future<Initial> seastar::map_reduce ( Iterator  begin,
Iterator  end,
Mapper &&  mapper,
Initial  initial,
Reduce  reduce 
)
inline

Asynchronous map/reduce transformation.

Given a range of objects, an asynchronous unary function operating on these objects, an initial value, and a binary function for reducing, map_reduce() will transform each object in the range, then apply the the reducing function to the result.

Example:

Calculate the total size of several files:

map_reduce(files.begin(), files.end(),
std::mem_fn(file::size),
size_t(0),
std::plus<size_t>())

Requirements:

  • Iterator: an InputIterator.
  • Mapper: unary function taking Iterator::value_type and producing a future<...>.
  • Initial: any value type
  • Reduce: a binary function taking two Initial values and returning an Initial

Return type:

  • future<Initial>
Parameters
beginbeginning of object range to operate on
endend of object range to operate on
mappermap function to call on each object, returning a future
initialinitial input value to reduce function
reducebinary function for merging two result values from mapper
Returns
equivalent to reduce(reduce(initial, mapper(obj0)), mapper(obj1)) ...

◆ map_reduce() [2/2]

template<typename Range , typename Mapper , typename Initial , typename Reduce >
future<Initial> seastar::map_reduce ( Range &&  range,
Mapper &&  mapper,
Initial  initial,
Reduce  reduce 
)
inline

Asynchronous map/reduce transformation (range version).

Given a range of objects, an asynchronous unary function operating on these objects, an initial value, and a binary function for reducing, map_reduce() will transform each object in the range, then apply the the reducing function to the result.

Example:

Calculate the total size of several files:

std::vector<file> files = ...;
map_reduce(files,
std::mem_fn(file::size),
size_t(0),
std::plus<size_t>())

Requirements:

  • Iterator: an InputIterator.
  • Mapper: unary function taking Iterator::value_type and producing a future<...>.
  • Initial: any value type
  • Reduce: a binary function taking two Initial values and returning an Initial

Return type:

  • future<Initial>
Parameters
rangeobject range to operate on
mappermap function to call on each object, returning a future
initialinitial input value to reduce function
reducebinary function for merging two result values from mapper
Returns
equivalent to reduce(reduce(initial, mapper(obj0)), mapper(obj1)) ...

◆ parallel_for_each() [1/2]

template<typename Iterator , typename Func >
future seastar::parallel_for_each ( Iterator  begin,
Iterator  end,
Func &&  func 
)
inline

Run tasks in parallel (iterator version).

Given a range [begin, end) of objects, run func on each *i in the range, and return a future<> that resolves when all the functions complete. func should return a future<> that indicates when it is complete. All invocations are performed in parallel.

Parameters
beginan InputIterator designating the beginning of the range
endan InputIterator designating the end of the range
funcFunction to apply to each element in the range (returning a future<>)
Returns
a future<> that resolves when all the function invocations complete. If one or more return an exception, the return value contains one of the exceptions.

◆ parallel_for_each() [2/2]

template<typename Range , typename Func >
future seastar::parallel_for_each ( Range &&  range,
Func &&  func 
)
inline

Run tasks in parallel (range version).

Given a range of objects, apply func to each object in the range, and return a future<> that resolves when all the functions complete. func should return a future<> that indicates when it is complete. All invocations are performed in parallel.

Parameters
rangeA range of objects to iterate run func on
funcA callable, accepting reference to the range's value_type, and returning a future<>.
Returns
a future<> that becomes ready when the entire range was processed. If one or more of the invocations of func returned an exceptional future, then the return value will contain one of those exceptions.

◆ repeat()

template<typename AsyncAction >
future seastar::repeat ( AsyncAction &&  action)
inline

Invokes given action until it fails or the function requests iteration to stop by returning stop_iteration::yes.

Parameters
actiona callable taking no arguments, returning a future<stop_iteration>. Will be called again as soon as the future resolves, unless the future fails, action throws, or it resolves with stop_iteration::yes. If action is an r-value it can be moved in the middle of iteration.
Returns
a ready future if we stopped successfully, or a failed future if a call to to action failed.

◆ repeat_until_value()

template<typename AsyncAction >
repeat_until_value_return_type<AsyncAction> seastar::repeat_until_value ( AsyncAction &&  action)

Invokes given action until it fails or the function requests iteration to stop by returning an engaged future<std::experimental::optional<T>>. The value is extracted from the optional, and returned, as a future, from repeat_until_value().

Parameters
actiona callable taking no arguments, returning a future<std::experimental::optional<T>>. Will be called again as soon as the future resolves, unless the future fails, action throws, or it resolves with an engaged optional. If action is an r-value it can be moved in the middle of iteration.
Returns
a ready future if we stopped successfully, or a failed future if a call to to action failed. The optional's value is returned.

◆ when_all() [1/2]

template<typename... Futs>
future<std::tuple<Futs...> > seastar::when_all ( Futs &&...  futs)
inline

Wait for many futures to complete, capturing possible errors (variadic version).

Given a variable number of futures as input, wait for all of them to resolve (either successfully or with an exception), and return them as a tuple so individual values or exceptions can be examined.

Parameters
futsfutures to wait for
Returns
an std::tuple<> of all the futures in the input; when ready, all contained futures will be ready as well.

◆ when_all() [2/2]

template<typename FutureIterator >
future<std::vector<typename std::iterator_traits<FutureIterator>::value_type> > seastar::when_all ( FutureIterator  begin,
FutureIterator  end 
)
inline

Wait for many futures to complete, capturing possible errors (iterator version).

Given a range of futures as input, wait for all of them to resolve (either successfully or with an exception), and return them as a std::vector so individual values or exceptions can be examined.

Parameters
beginan InputIterator designating the beginning of the range of futures
endan InputIterator designating the end of the range of futures
Returns
an std::vector<> of all the futures in the input; when ready, all contained futures will be ready as well.

◆ when_all_succeed() [1/2]

template<typename... Futures>
auto seastar::when_all_succeed ( Futures &&...  futures)
inline

Wait for many futures to complete (variadic version).

Given a variable number of futures as input, wait for all of them to resolve, and return a future containing the values of each individual resolved future. In case any of the given futures fails one of the exceptions is returned by this function as a failed future.

Parameters
futuresfutures to wait for
Returns
future containing values of input futures

◆ when_all_succeed() [2/2]

template<typename FutureIterator , typename = typename std::iterator_traits<FutureIterator>::value_type>
auto seastar::when_all_succeed ( FutureIterator  begin,
FutureIterator  end 
)
inline

Wait for many futures to complete (iterator version).

Given a range of futures as input, wait for all of them to resolve, and return a future containing a vector of values of the original futures. In case any of the given futures fails one of the exceptions is returned by this function as a failed future.

Parameters
beginan InputIterator designating the beginning of the range of futures
endan InputIterator designating the end of the range of futures
Returns
an std::vector<> of all the valus in the input

◆ with_lock()

template<typename Lock , typename Func >
auto seastar::with_lock ( Lock &  lock,
Func &&  func 
)
inline

Executes the function func making sure the lock lock is taken, and later on properly released.

Parameters
lockthe lock, which is any object having providing a lock() / unlock() semantics. Caller must make sure that it outlives func.
funcfunction to be executed
Returns
whatever func returns

◆ with_scheduling_group()

template<typename Func , typename... Args>
auto seastar::with_scheduling_group ( scheduling_group  sg,
Func  func,
Args &&...  args 
)
inline

run a callable (with some arbitrary arguments) in a scheduling group

If the conditions are suitable (see scheduling_group::may_run_immediately()), then the function is run immediately. Otherwise, the function is queued to run when its scheduling group next runs.

Parameters
sgscheduling group that controls execution time for the function
funcfunction to run; must be movable or copyable
argsarguments to the function; may be copied or moved, so use std::ref() to force passing references

◆ with_timeout()

template<typename ExceptionFactory = default_timeout_exception_factory, typename Clock , typename Duration , typename... T>
future<T...> seastar::with_timeout ( std::chrono::time_point< Clock, Duration >  timeout,
future< T... >  f 
)

Wait for either a future, or a timeout, whichever comes first.

When timeout is reached the returned future resolves with an exception produced by ExceptionFactory::timeout(). By default it is timed_out_error exception.

Note that timing out doesn't cancel any tasks associated with the original future. It also doesn't cancel the callback registerred on it.

Parameters
ffuture to wait for
timeouttime point after which the returned future should be failed
Returns
a future which will be either resolved with f or a timeout exception