Seastar
High performance C++ framework for concurrent servers
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Classes | Functions
Execution Stages

Detailed Description

Execution stages provide an infrastructure for processing function calls in batches in order to improve instruction cache locality.

When the application logic becomes more and more complex and the length of the data processing pipeline grows it may happen that the most significant bottleneck are instruction cache misses. The solution for that problem may be processing similar operations in batches so that instruction cache locality is improved at the cost of potentially higher latencies and worse data cache locality.

Execution stages allow batching calls to the specified function object. Every time concrete_execution_stage::operator()() is used the function call is added to the queue and a future is returned. Once the number of queued calls reaches certain threshold the stage is flushed and a task is which would execute these function calls is scheduled. Execution stages are also flushed when the reactor polls for events.

When calling a function that is wrapped inside execution stage it is important to remember that the actual function call will happen at some later time and it has to be guaranteed the objects passed by lvalue reference are still alive. In order to avoid accidental passing of a temporary object by lvalue reference the interface of execution stages accepts only lvalue references wrapped in reference_wrapper. It is safe to pass rvalue references, they are decayed and the objects are moved. See concrete_execution_stage::operator()() for more details.

Classes

class  seastar::execution_stage
 Base execution stage class. More...
 
class  seastar::concrete_execution_stage< ReturnType, Args >
 Concrete execution stage class. More...
 
class  seastar::inheriting_execution_stage
 Base class for execution stages with support for automatic scheduling_group inheritance. More...
 
class  seastar::inheriting_concrete_execution_stage< ReturnType, Args >
 Concrete execution stage class, with support for automatic scheduling_group inheritance. More...
 

Functions

template<typename Function >
auto seastar::make_execution_stage (const sstring &name, scheduling_group sg, Function &&fn)
 
template<typename Function >
auto seastar::make_execution_stage (const sstring &name, Function &&fn)
 
template<typename Ret , typename Object , typename... Args>
concrete_execution_stage< Ret, Object *, Args... > seastar::make_execution_stage (const sstring &name, scheduling_group sg, Ret(Object::*fn)(Args...))
 
template<typename Ret , typename Object , typename... Args>
concrete_execution_stage< Ret, Object *, Args... > seastar::make_execution_stage (const sstring &name, Ret(Object::*fn)(Args...))
 

Function Documentation

◆ make_execution_stage() [1/3]

template<typename Function >
auto seastar::make_execution_stage ( const sstring &  name,
Function &&  fn 
)

Creates a new execution stage (variant taking scheduling_group)

Wraps given function object in a concrete_execution_stage. All arguments of the function object are required to have move constructors that do not throw. Function object may return a future or an immediate object or void.

Moving execution stages is discouraged and illegal after first function call is enqueued.

Usage example:

double do_something(int);
thread_local auto stage1 = seastar::make_execution_stage("execution-stage1", do_something);
future<double> func1(int val) {
return stage1(val);
}
future<double> do_some_io(int);
thread_local auto stage2 = seastar::make_execution_stage("execution-stage2", do_some_io);
future<double> func2(int val) {
return stage2(val);
}
A representation of a possibly not-yet-computed value.
Definition: future.hh:1240
auto make_execution_stage(const sstring &name, scheduling_group sg, Function &&fn)
Definition: execution_stage.hh:451
Parameters
nameunique name of the execution stage (variant not taking scheduling_group)
fnfunction to be executed by the stage
Returns
concrete_execution_stage

◆ make_execution_stage() [2/3]

template<typename Function >
auto seastar::make_execution_stage ( const sstring &  name,
scheduling_group  sg,
Function &&  fn 
)

Creates a new execution stage

Wraps given function object in a concrete_execution_stage. All arguments of the function object are required to have move constructors that do not throw. Function object may return a future or an immediate object or void.

Moving execution stages is discouraged and illegal after first function call is enqueued.

Usage example:

double do_something(int);
thread_local auto stage1 = seastar::make_execution_stage("execution-stage1", do_something);
future<double> func1(int val) {
return stage1(val);
}
future<double> do_some_io(int);
thread_local auto stage2 = seastar::make_execution_stage("execution-stage2", do_some_io);
future<double> func2(int val) {
return stage2(val);
}
Parameters
nameunique name of the execution stage
sgscheduling group to run under
fnfunction to be executed by the stage
Returns
concrete_execution_stage

◆ make_execution_stage() [3/3]

template<typename Ret , typename Object , typename... Args>
concrete_execution_stage< Ret, Object *, Args... > seastar::make_execution_stage ( const sstring &  name,
scheduling_group  sg,
Ret(Object::*)(Args...)  fn 
)

Creates a new execution stage from a member function

Wraps a pointer to member function in a concrete_execution_stage. When a function call is pushed to the stage the first argument should be a pointer to the object the function is a member of.

Usage example:

struct foo {
void do_something(int);
};
thread_local auto stage = seastar::make_execution_stage("execution-stage", &foo::do_something);
future<> func(foo& obj, int val) {
return stage(&obj, val);
}
See also
make_execution_stage(const sstring&, Function&&)
Parameters
nameunique name of the execution stage
fnmember function to be executed by the stage
Returns
concrete_execution_stage