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

Service

a 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
sharded &	operator= (const sharded &other)=delete
	sharded (sharded &&other)=delete
sharded &	operator= (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 Func , typename... Args>
auto	map_reduce (Reducer &&r, Func &&func, Args &&... args) -> typename reducer_traits< Reducer >::future_type
template<typename Reducer , typename Func , typename... Args>
auto	map_reduce (Reducer &&r, Func &&func, Args &&... args) 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::invoke_result_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

id	shard id to call
func	a callable with signature Value (Service&) or future<Value> (Service&) (for some Value type), or a pointer to a member function of Service
args	parameters 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

id	shard id to call
options	the options to forward to the smp::submit_to() called behind the scenes.
func	a callable with signature Value (Service&, Args...) or future<Value> (Service&, Args...) (for some Value type), or a pointer to a member function of Service
args	parameters 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

options	the options to forward to the smp::submit_to() called behind the scenes.
func	invocable 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

options	the options to forward to the smp::submit_to() called behind the scenes.
func	Function 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

func	a 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

options	the options to forward to the smp::submit_to() called behind the scenes.
func	a 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::invoke_result_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

mapper

callable 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

Mapper

unary function taking Service& and producing some result.

Returns

Result vector of invoking map with each instance in parallel

map_reduce()

template<typename Service >

template<typename Reducer , typename Func , typename... Args>

auto seastar::sharded< Service >::map_reduce ( Reducer &&  r, Func &&  func, Args &&...  args  ) -> 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_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

map	callable with the signature Value (Service&) or future<Value> (Service&) (for some Value type). used as the second input to reduce
initial	initial value used as the first input to reduce.
reduce	binary 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

Mapper	unary function taking Service& and producing some result.
Initial	any value type
Reduce	a 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

args	Arguments 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

args	Arguments 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:

• seastar/core/sharded.hh