Seastar
High performance C++ framework for concurrent servers
Classes | Public Member Functions | List of all members
seastar::sharded< Service > Class Template Reference

Detailed Description

template<typename Service>
class seastar::sharded< Service >

Template helper to distribute a service across all logical cores.

The sharded template manages a sharded service, by creating a copy of the service on each logical core, providing mechanisms to communicate with each shard's copy, and a way to stop the service.

Template Parameters
Servicea class to be instantiated on each core. Must expose a stop() method that returns a future<>, to be called when the service is stopped.
Examples
sharded_parameter_demo.cc.

#include <seastar/core/sharded.hh>

Public Member Functions

 sharded () noexcept
 
 sharded (const sharded &other)=delete
 
shardedoperator= (const sharded &other)=delete
 
 sharded (sharded &&other)=delete
 
shardedoperator= (sharded &&other)=delete
 
 ~sharded ()
 Destroyes a sharded object. Must not be in a started state.
 
template<typename... Args>
future start (Args &&... args) noexcept
 
template<typename... Args>
future start_single (Args &&... args) noexcept
 
future stop () noexcept
 
future invoke_on_all (smp_submit_to_options options, std::function< future<>(Service &)> func) noexcept
 
future invoke_on_all (std::function< future<>(Service &)> func) noexcept
 
template<typename Func , typename... Args>
future invoke_on_all (smp_submit_to_options options, Func func, Args... args) noexcept
 
template<typename Func , typename... Args>
future invoke_on_all (Func func, Args... args) noexcept
 
template<typename Func , typename... Args>
future invoke_on_others (smp_submit_to_options options, Func func, Args... args) noexcept
 
template<typename Func , typename... Args>
future invoke_on_others (Func func, Args... args) noexcept
 
template<typename Reducer , typename Ret , typename... FuncArgs, typename... Args>
auto map_reduce (Reducer &&r, Ret(Service::*func)(FuncArgs...), Args &&... args) -> typename reducer_traits< Reducer >::future_type
 
template<typename Reducer , typename Func >
auto map_reduce (Reducer &&r, Func &&func) -> typename reducer_traits< Reducer >::future_type
 
template<typename Reducer , typename Func >
auto map_reduce (Reducer &&r, Func &&func) const -> typename reducer_traits< Reducer >::future_type
 The const version of map_reduce(Reducer&& r, Func&& func)
 
template<typename Mapper , typename Initial , typename Reduce >
future< Initial > map_reduce0 (Mapper map, Initial initial, Reduce reduce)
 
template<typename Mapper , typename Initial , typename Reduce >
future< Initial > map_reduce0 (Mapper map, Initial initial, Reduce reduce) const
 The const version of map_reduce0(Mapper map, Initial initial, Reduce reduce)
 
template<typename Mapper , typename Future = futurize_t<std::result_of_t<Mapper(Service&)>>, typename return_type = decltype(internal::untuple(std::declval<typename Future::tuple_type>()))>
future< std::vector< return_type > > map (Mapper mapper)
 
template<typename Func , typename... Args, typename Ret = futurize_t<std::invoke_result_t<Func, Service&, Args...>>>
Ret invoke_on (unsigned id, smp_submit_to_options options, Func &&func, Args &&... args)
 
template<typename Func , typename... Args, typename Ret = futurize_t<std::invoke_result_t<Func, Service&, Args&&...>>>
Ret invoke_on (unsigned id, Func &&func, Args &&... args)
 
const Service & local () const noexcept
 Gets a reference to the local instance.
 
Service & local () noexcept
 Gets a reference to the local instance.
 
shared_ptr< Service > local_shared () noexcept
 Gets a shared pointer to the local instance.
 
bool local_is_initialized () const noexcept
 Checks whether the local instance has been initialized.
 

Constructor & Destructor Documentation

◆ sharded() [1/2]

template<typename Service >
seastar::sharded< Service >::sharded ( )
inlinenoexcept

Constructs an empty sharded object. No instances of the service are created.

◆ sharded() [2/2]

template<typename Service >
seastar::sharded< Service >::sharded ( sharded< Service > &&  other)
delete

Sharded object with T that inherits from peering_sharded_service cannot be moved safely, so disable move operations.

Member Function Documentation

◆ invoke_on() [1/2]

template<typename Service >
template<typename Func , typename... Args, typename Ret = futurize_t<std::invoke_result_t<Func, Service&, Args&&...>>>
Ret seastar::sharded< Service >::invoke_on ( unsigned  id,
Func &&  func,
Args &&...  args 
)
inline

Invoke a callable on a specific instance of Service.

Parameters
idshard id to call
funca callable with signature Value (Service&) or future<Value> (Service&) (for some Value type), or a pointer to a member function of Service
argsparameters to the callable
Returns
result of calling func(instance) on the designated instance

◆ invoke_on() [2/2]

template<typename Service >
template<typename Func , typename... Args, typename Ret = futurize_t<std::invoke_result_t<Func, Service&, Args...>>>
Ret seastar::sharded< Service >::invoke_on ( unsigned  id,
smp_submit_to_options  options,
Func &&  func,
Args &&...  args 
)
inline

Invoke a callable on a specific instance of Service.

Parameters
idshard id to call
optionsthe options to forward to the smp::submit_to() called behind the scenes.
funca callable with signature Value (Service&, Args...) or future<Value> (Service&, Args...) (for some Value type), or a pointer to a member function of Service
argsparameters to the callable; will be copied or moved. To pass by reference, use std::ref().
Returns
result of calling func(instance) on the designated instance

◆ invoke_on_all() [1/4]

template<typename Service >
template<typename Func , typename... Args>
future seastar::sharded< Service >::invoke_on_all ( Func  func,
Args...  args 
)
inlinenoexcept

Invoke a function on all instances of Service. The return value becomes ready when all instances have processed the message. Passes the default smp_submit_to_options to the smp::submit_to() called behind the scenes.

◆ invoke_on_all() [2/4]

template<typename Service >
template<typename Func , typename... Args>
future seastar::sharded< Service >::invoke_on_all ( smp_submit_to_options  options,
Func  func,
Args...  args 
)
inlinenoexcept

Invoke a function on all instances of Service. The return value becomes ready when all instances have processed the message. The function can be a member pointer to function, a free function, or a functor. The first argument of the function will be a reference to the local service on the shard.

For a non-static pointer-to-member-function, the first argument becomes this, not the first declared parameter.

Parameters
optionsthe options to forward to the smp::submit_to() called behind the scenes.
funcinvocable accepting a Service& as the first parameter to be invoked on all shards
Returns
Future that becomes ready once all calls have completed

◆ invoke_on_all() [3/4]

template<typename Service >
future seastar::sharded< Service >::invoke_on_all ( smp_submit_to_options  options,
std::function< future<>(Service &)>  func 
)
noexcept

Invoke a type-erased function on all instances of Service. The return value becomes ready when all instances have processed the message.

Parameters
optionsthe options to forward to the smp::submit_to() called behind the scenes.
funcFunction to be invoked on all shards
Returns
Future that becomes ready once all calls have completed
Examples
sharded_parameter_demo.cc.

◆ invoke_on_all() [4/4]

template<typename Service >
future seastar::sharded< Service >::invoke_on_all ( std::function< future<>(Service &)>  func)
inlinenoexcept

Invoke a type-erased function on all instances of Service. The return value becomes ready when all instances have processed the message. Passes the default smp_submit_to_options to the smp::submit_to() called behind the scenes.

◆ invoke_on_others() [1/2]

template<typename Service >
template<typename Func , typename... Args>
future seastar::sharded< Service >::invoke_on_others ( Func  func,
Args...  args 
)
inlinenoexcept

Invoke a callable on all instances of Service except the instance which is allocated on current shard.

Parameters
funca callable with the signature void (Service&) or future<> (Service&), to be called on each core with the local instance as an argument.
Returns
a future<> that becomes ready when all cores but the current one have processed the message.

Passes the default smp_submit_to_options to the smp::submit_to() called behind the scenes.

◆ invoke_on_others() [2/2]

template<typename Service >
template<typename Func , typename... Args>
future seastar::sharded< Service >::invoke_on_others ( smp_submit_to_options  options,
Func  func,
Args...  args 
)
inlinenoexcept

Invoke a callable on all instances of Service except the instance which is allocated on current shard.

Parameters
optionsthe options to forward to the smp::submit_to() called behind the scenes.
funca callable with the signature void (Service&) or future<> (Service&), to be called on each core with the local instance as an argument.
Returns
a future<> that becomes ready when all cores but the current one have processed the message.

◆ map()

template<typename Service >
template<typename Mapper , typename Future = futurize_t<std::result_of_t<Mapper(Service&)>>, typename return_type = decltype(internal::untuple(std::declval<typename Future::tuple_type>()))>
future<std::vector<return_type> > seastar::sharded< Service >::map ( Mapper  mapper)
inline

Applies a map function to all shards, and return a vector of the result.

Parameters
mappercallable with the signature Value (Service&) or future<Value> (Service&) (for some Value type).

Each map invocation runs on the shard associated with the service.

Template Parameters
Mapperunary function taking Service& and producing some result.
Returns
Result vector of invoking map with each instance in parallel

◆ map_reduce() [1/2]

template<typename Service >
template<typename Reducer , typename Func >
auto seastar::sharded< Service >::map_reduce ( Reducer &&  r,
Func &&  func 
) -> typename reducer_traits<Reducer>::future_type
inline

Invoke a callable on all instances of Service and reduce the results using Reducer.

See also
map_reduce(Iterator begin, Iterator end, Mapper&& mapper, Reducer&& r)

◆ map_reduce() [2/2]

template<typename Service >
template<typename Reducer , typename Ret , typename... FuncArgs, typename... Args>
auto seastar::sharded< Service >::map_reduce ( Reducer &&  r,
Ret(Service::*)(FuncArgs...)  func,
Args &&...  args 
) -> typename reducer_traits<Reducer>::future_type
inline

Invoke a method on all instances of Service and reduce the results using Reducer.

See also
map_reduce(Iterator begin, Iterator end, Mapper&& mapper, Reducer&& r)

◆ map_reduce0()

template<typename Service >
template<typename Mapper , typename Initial , typename Reduce >
future<Initial> seastar::sharded< Service >::map_reduce0 ( Mapper  map,
Initial  initial,
Reduce  reduce 
)
inline

Applies a map function to all shards, then reduces the output by calling a reducer function.

Parameters
mapcallable with the signature Value (Service&) or future<Value> (Service&) (for some Value type). used as the second input to reduce
initialinitial value used as the first input to reduce.
reducebinary function used to left-fold the return values of map into initial .

Each map invocation runs on the shard associated with the service.

Template Parameters
Mapperunary function taking Service& and producing some result.
Initialany value type
Reducea binary function taking two Initial values and returning an Initial
Returns
Result of invoking map with each instance in parallel, reduced by calling reduce() on each adjacent pair of results.

◆ start()

template<typename Service >
template<typename... Args>
future seastar::sharded< Service >::start ( Args &&...  args)
noexcept

Starts Service by constructing an instance on every logical core with a copy of args passed to the constructor.

Parameters
argsArguments to be forwarded to Service constructor
Returns
a seastar::future<> that becomes ready when all instances have been constructed.
Examples
sharded_parameter_demo.cc.

◆ start_single()

template<typename Service >
template<typename... Args>
future seastar::sharded< Service >::start_single ( Args &&...  args)
noexcept

Starts Service by constructing an instance on a single logical core with a copy of args passed to the constructor.

Parameters
argsArguments to be forwarded to Service constructor
Returns
a seastar::future<> that becomes ready when the instance has been constructed.

◆ stop()

template<typename Service >
future seastar::sharded< Service >::stop
noexcept

Stops all started instances and destroys them.

For every started instance, its stop() method is called, and then it is destroyed.


The documentation for this class was generated from the following file: