Seastar
High performance C++ framework for concurrent servers
|
These utilities are provided to help perform operations on futures.
Classes | |
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... | |
struct | seastar::stop_iteration_tag |
class | seastar::adder< Result, Addend > |
Typedefs | |
template<typename T > | |
using | seastar::futurize_t = typename futurize< T >::type |
using | seastar::stop_iteration = bool_class< stop_iteration_tag > |
Functions | |
template<typename T1 , typename T2 , typename... More> | |
auto | seastar::do_with (T1 &&rv1, T2 &&rv2, More &&... more) noexcept |
template<typename Lock , typename Func > | |
auto | seastar::with_lock (Lock &lock, Func &&func) |
template<typename AsyncAction > | |
future | seastar::repeat (const AsyncAction &action) noexcept=delete |
template<typename AsyncAction > | |
future | seastar::repeat (AsyncAction &action) noexcept=delete |
template<typename AsyncAction > requires std::is_invocable_r_v<stop_iteration, AsyncAction> || std::is_invocable_r_v<future<stop_iteration>, AsyncAction> | |
future | seastar::repeat (AsyncAction &&action) noexcept |
template<typename AsyncAction > requires requires (AsyncAction aa) { bool(futurize_invoke(aa).get()); futurize_invoke(aa).get().value(); } | |
repeat_until_value_return_type< AsyncAction > | seastar::repeat_until_value (AsyncAction action) noexcept |
template<typename AsyncAction , typename StopCondition > requires std::is_invocable_r_v<bool, StopCondition> && std::is_invocable_r_v<future<>, AsyncAction> | |
future | seastar::do_until (StopCondition stop_cond, AsyncAction action) noexcept |
template<typename AsyncAction > requires std::is_invocable_r_v<future<>, AsyncAction> | |
future | seastar::keep_doing (AsyncAction action) noexcept |
template<typename Iterator , typename Sentinel , typename AsyncAction > requires ( requires (Iterator i, AsyncAction aa) { { futurize_invoke(aa, *i) } -> std::same_as<future<>>; } && (std::same_as<Sentinel, Iterator> || std::sentinel_for<Sentinel, Iterator>) ) | |
future | seastar::do_for_each (Iterator begin, Sentinel end, AsyncAction action) noexcept |
Call a function for each item in a range, sequentially (iterator version). More... | |
template<typename Range , typename AsyncAction > requires requires (Range c, AsyncAction aa) { { futurize_invoke(aa, *std::begin(c)) } -> std::same_as<future<>>; std::end(c); } | |
future | seastar::do_for_each (Range &c, AsyncAction action) noexcept |
Call a function for each item in a range, sequentially (range version). More... | |
template<typename Iterator , typename Sentinel , typename Func > requires (requires (Func f, Iterator i) { { f(*i) } -> std::same_as<future<>>; { i++ }; } && (std::same_as<Sentinel, Iterator> || std::sentinel_for<Sentinel, Iterator>)) | |
future | seastar::parallel_for_each (Iterator begin, Sentinel end, Func &&func) noexcept |
Run tasks in parallel (iterator version). More... | |
template<typename Range , typename Func > requires requires (Func f, Range r) { { f(*std::begin(r)) } -> std::same_as<future<>>; std::end(r); } | |
future | seastar::parallel_for_each (Range &&range, Func &&func) noexcept |
template<typename Iterator , typename Sentinel , typename Func > requires (requires (Func f, Iterator i) { { f(*i) } -> std::same_as<future<>>; { ++i }; } && (std::same_as<Sentinel, Iterator> || std::sentinel_for<Sentinel, Iterator>) ) | |
future | seastar::max_concurrent_for_each (Iterator begin, Sentinel end, size_t max_concurrent, Func &&func) noexcept |
template<typename Range , typename Func > requires requires (Func f, Range r) { { f(*std::begin(r)) } -> std::same_as<future<>>; std::end(r); } | |
future | seastar::max_concurrent_for_each (Range &&range, size_t max_concurrent, Func &&func) noexcept |
template<typename Iterator , typename Mapper , typename Reducer > requires requires (Iterator i, Mapper mapper, Reducer reduce) { *i++; { i != i } -> std::convertible_to<bool>; mapper(*i); reduce(futurize_invoke(mapper, *i).get()); } | |
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 > requires requires (Iterator i, Mapper mapper, Initial initial, Reduce reduce) { *i++; { i != i} -> std::convertible_to<bool>; mapper(*i); requires is_future<decltype(mapper(*i))>::value; { reduce(std::move(initial), mapper(*i).get()) } -> std::convertible_to<Initial>; } | |
future< Initial > | seastar::map_reduce (Iterator begin, Iterator end, Mapper &&mapper, Initial initial, Reduce reduce) |
template<typename Range , typename Mapper , typename Initial , typename Reduce > requires requires (Range range, Mapper mapper, Initial initial, Reduce reduce) { std::begin(range); std::end(range); mapper(*std::begin(range)); requires is_future<std::remove_reference_t<decltype(mapper(*std::begin(range)))>>::value; { reduce(std::move(initial), mapper(*std::begin(range)).get()) } -> std::convertible_to<Initial>; } | |
future< Initial > | seastar::map_reduce (Range &&range, Mapper &&mapper, Initial initial, Reduce reduce) |
template<typename... FutOrFuncs> | |
auto | seastar::when_all (FutOrFuncs &&... fut_or_funcs) noexcept |
template<typename FutureIterator > requires requires (FutureIterator i) { { *i++ }; requires is_future<std::remove_reference_t<decltype(*i)>>::value; } | |
future< std::vector< typename std::iterator_traits< FutureIterator >::value_type > > | seastar::when_all (FutureIterator begin, FutureIterator end) noexcept |
template<typename... FutOrFuncs> | |
auto | seastar::when_all_succeed (FutOrFuncs &&... fut_or_funcs) noexcept |
template<typename FutureIterator , typename = typename std::iterator_traits<FutureIterator>::value_type> requires requires (FutureIterator i) { *i++; { i != i } -> std::convertible_to<bool>; requires is_future<std::remove_reference_t<decltype(*i)>>::value; } | |
auto | seastar::when_all_succeed (FutureIterator begin, FutureIterator end) noexcept |
template<typename T > | |
auto | seastar::when_all_succeed (std::vector< future< T > > &&futures) noexcept |
template<typename Func , typename... Args> requires std::is_nothrow_move_constructible_v<Func> | |
auto | seastar::with_scheduling_group (scheduling_group sg, Func func, Args &&... args) noexcept |
run a callable (with some arbitrary arguments) in a scheduling group More... | |
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... | |
future | seastar::now () |
Returns a ready future. | |
future | seastar::yield () noexcept |
Returns a future which is not ready but is scheduled to resolve soon. More... | |
future | seastar::maybe_yield () noexcept |
future | seastar::check_for_io_immediately () noexcept |
future | seastar::later () noexcept |
Returns a future which is not ready but is scheduled to resolve soon. More... | |
struct seastar::stop_iteration_tag |
|
noexcept |
Force the reactor to check for pending I/O
Schedules a check for new I/O completions (disk operations completions or network packet arrival) immediately and return a future that is ready when the I/O has been polled for.
|
inlinenoexcept |
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.
begin | an InputIterator designating the beginning of the range |
end | an InputIterator designating the endof the range |
action | a 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. |
action
failed.
|
inlinenoexcept |
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.
c | an Range object designating input range |
action | a 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. |
action
failed.
|
inlinenoexcept |
Invokes given action until it fails or given condition evaluates to true or fails.
stop_cond | a callable taking no arguments, returning a boolean that evalutes to true when you don't want to call action any longer. If stop_cond fails, the exception is propagated |
action | a 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 or fails. |
action
or a call to stop_cond
failed.
|
inlinenoexcept |
do_with() holds a objects alive until a future completes, and allow the code involved in making the future complete to have easy access to this object.
do_with() takes multiple arguments: The last is a function returning a future. The other are temporary objects (rvalue). The function is given (a moved copy of) these temporary object, by reference, and it is ensured that the objects 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.
|
inlinenoexcept |
Invoke given action until it fails.
Calls action
repeatedly until it returns a failed future.
action | a callable taking no arguments, returning a future<> that becomes ready when you wish it to be called again. |
action
|
noexcept |
Returns a future which is not ready but is scheduled to resolve soon.
|
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 invoke the the reducing function with the result.
Example:
Calculate the total size of several files:
Requirements:
Return type:
begin | beginning of object range to operate on |
end | end of object range to operate on |
mapper | map function to call on each object, returning a future |
initial | initial input value to reduce function |
reduce | binary function for merging two result values from mapper |
reduce
(reduce(initial, mapper(obj0)), mapper(obj1)) ...mapper
and reduce
on the current shard. If you want to run a function on all shards in parallel, have a look at smp::invoke_on_all() instead, or combine map_reduce() with smp::submit_to(). Sharded services have their own sharded::map_reduce() which map-reduces across all shards.
|
inline |
Map a function over a range and reduce the result.
begin | an InputIterator designating the beginning of the range |
end | an InputIterator designating the end of the range |
mapper | is a callable which transforms values from the iterator range into a future<T> |
r | is an object which can be called with T as parameter and yields a future<> It may have a get() method which returns a value of type U which holds the result of reduction. |
mapper
and reduce
on the current shard. If you want to run a function on all shards in parallel, have a look at smp::invoke_on_all() instead, or combine map_reduce() with smp::submit_to(). Sharded services have their own sharded::map_reduce() which map-reduces across all shards.
|
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 invoke the the reducing function with the result.
Example:
Calculate the total size of several files:
Requirements:
Return type:
range | object range to operate on |
mapper | map function to call on each object, returning a future |
initial | initial input value to reduce function |
reduce | binary function for merging two result values from mapper |
reduce
(reduce(initial, mapper(obj0)), mapper(obj1)) ...mapper
and reduce
on the current shard. If you want to run a function on all shards in parallel, have a look at smp::invoke_on_all() instead, or combine map_reduce() with smp::submit_to(). Sharded services have their own sharded::map_reduce() which map-reduces across all shards.
|
inlinenoexcept |
Run a maximum of max_concurrent
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. Up to max_concurrent
invocations are performed in parallel. This does not allow the range to refer to stack objects. The caller must ensure that the range outlives the call to max_concurrent_for_each so it can be iterated in the background.
begin | an InputIterator designating the beginning of the range |
end | an InputIterator designating the end of the range |
max_concurrent | maximum number of concurrent invocations of func , must be greater than zero. |
func | Function to invoke with each element in the range (returning a future<> ) |
future<>
that resolves when all the function invocations complete. If one or more return an exception, the return value contains one of the exceptions. func
on the current shard. If you want to run a function on all shards in parallel, have a look at smp::invoke_on_all() instead.
|
inlinenoexcept |
Run a maximum of max_concurrent
tasks in parallel (range version).
Given a range 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. Up to max_concurrent
invocations are performed in parallel. This does not allow the range to refer to stack objects. The caller must ensure that the range outlives the call to max_concurrent_for_each so it can be iterated in the background.
range | a Range to be processed |
max_concurrent | maximum number of concurrent invocations of func , must be greater than zero. |
func | Function to invoke with each element in the range (returning a future<> ) |
future<>
that resolves when all the function invocations complete. If one or more return an exception, the return value contains one of the exceptions. func
on the current shard. If you want to run a function on all shards in parallel, have a look at smp::invoke_on_all() instead.
|
inlinenoexcept |
Yield the cpu if the task quota is exhausted.
Check if the current continuation is preempted and yield if so. Otherwise return a ready future.
|
inlinenoexcept |
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. This allows the range to refer to stack objects, but means that unlike other loops this cannot check need_preempt and can only be used with small ranges.
begin | an InputIterator designating the beginning of the range |
end | an InputIterator designating the end of the range |
func | Function to invoke with each element in the range (returning a future<> ) |
future<>
that resolves when all the function invocations complete. If one or more return an exception, the return value contains one of the exceptions. func
on the current shard. If you want to run a function on all shards in parallel, have a look at smp::invoke_on_all() instead.
|
inlinenoexcept |
Invokes given action until it fails or the function requests iteration to stop by returning stop_iteration::yes
.
action | a 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. |
action
failed.
|
noexcept |
Invokes given action until it fails or the function requests iteration to stop by returning an engaged future<std::optional<T>>
or std::optional<T>. The value is extracted from the optional
, and returned, as a future, from repeat_until_value().
action | a callable taking no arguments, returning a future<std::optional<T>> or std::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. |
action
failed. The optional's
value is returned.
|
inlinenoexcept |
Wait for many futures to complete, capturing possible errors (variadic version).
Each future can be passed directly, or a function that returns a future can be given instead.
If any function throws, an exceptional future is created for it.
Returns a tuple of futures so individual values or exceptions can be examined.
fut_or_funcs | futures or functions that return futures |
std::tuple<>
of all futures returned; when ready, all contained futures will be ready as well.
|
inlinenoexcept |
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.
begin | an InputIterator designating the beginning of the range of futures |
end | an InputIterator designating the end of the range of futures |
std::vector<>
of all the futures in the input; when ready, all contained futures will be ready as well.
|
inlinenoexcept |
Wait for many futures to complete (variadic version).
Each future can be passed directly, or a function that returns a future can be given instead.
If any function throws, or if the returned future fails, one of the exceptions is returned by this function as a failed future.
fut_or_funcs | futures or functions that return futures |
|
inlinenoexcept |
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.
begin | an InputIterator designating the beginning of the range of futures |
end | an InputIterator designating the end of the range of futures |
std::vector<>
of all the valus in the input
|
inlinenoexcept |
Wait for many futures to complete (vector version).
Given a vector 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.
futures | a std::vector containing the futures to wait for. |
std::vector<>
of all the values in the input
|
inline |
Executes the function func
making sure the lock lock
is taken, and later on properly released.
lock | the lock, which is any object having providing a lock() / unlock() semantics. Caller must make sure that it outlives func . |
func | function to be executed |
func
returns
|
inlinenoexcept |
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.
sg | scheduling group that controls execution time for the function |
func | function to run; must be movable or copyable |
args | arguments to the function; may be copied or moved, so use std::ref() to force passing references |
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.
f | future to wait for |
timeout | time point after which the returned future should be failed |
|
noexcept |