Strand

class Strand : public std::enable_shared_from_this<Strand>

A poor man's substitute for boost::asio::strand because that does not guarantee that handlers posted on different strands can run in parallel ("strand collision"). Compared to boost::asio::strand, this - lacks dispatch: we usually do not want that in Karabo since it allows the handler to be called now in this scope - lacks running_in_this_thread: probably not too important - has a more restrictive wrap: would be useful to support more, but a proper implementation would also need dispatch

Every handler posted will be put into a FIFO queue and the FIFO will be emptied in the background by posting the handlers to the given boost::asio::io_context (either from net::EventLoop, passed in constructor, or defined by setContext(..)).

NOTE: Do not create a Strand on the stack, but do it on the heap using the Configurator:

auto stack = karabo::data::Configurator::create(Hash(...));

Otherwise 'enable_shared_from_this' does not work which is needed to guarantee (via usage of karab::util::bind_weak) that an internal Strand method is executed on the event loop when the Strand is already destructed.

Functions

Name	Description
Strand	Contructor only kept for backward compatibility.
Strand	Construct the Strand.
setContext	Set the context to which the handlers are to be posted.
post	Post a handler to the io_context with the guarantee that it is not executed before any other handler posted before has finished.
post	Post a handler to the io_context with the guarantee that it is not executed before any other handler posted before has finished.
wrap	This function is used to create a new handler function object that, when invoked, will pass the wrapped handler to the Strand's post function (instead of using dispatch as boost::io_service::strand::wrap does). handler : The handler to be wrapped. The strand will make a copy of the handler object. Compared to boost::io_service::strand::wrap, the handler signature is much more restricted, i.e. must be void(). Return : A function object that, when invoked, passes the wrapped handler to the Strand's post function.
getContext	This function may be used to obtain the io_context object that the strand uses to post handlers.
get_io_service	Deprecated.
startRunningIfNeeded	Helper for post - to be called under protection of m_tasksMutex!
run	Helper to run one task after another until tasks queue is empty

Function Details

Strand

explicit Strand(boost::asio::io_context& ioContext)

Contructor only kept for backward compatibility.

Better use karabo::data::Configurator::create("Strand", Hash())

explicit Strand(const karabo::data::Hash& config)

Construct the Strand.

The boost::asio::io_context of the karabo::net::EventLoop will be used.

Best use this constructor indirectly via karabo::data::Configurator::create("Strand", cfg) which will validate cfg and create the Strand properly on the heap.

Keys of cfg are "maxInARow" (unsigned int) and "guaranteeToRun" (bool), see expectedParameters.

getContext

boost::asio::io_context& getContext() const

This function may be used to obtain the io_context object that the strand uses to post handlers.

Return : A reference to the io_context of the Strand. Ownership is not transferred to the caller.

get_io_service

boost::asio::io_context& get_io_service() const

Deprecated.

Use getContext() instead.

post

void post(const std::function<void()>& handler)

Post a handler to the io_context with the guarantee that it is not executed before any other handler posted before has finished. Handlers posted on different Strands can always be run in parallel.

Note that "guaranteeToRun" flag of the constructor determines what happens with yet unhandled handlers when the Strand is destructed.

handler : function without arguments and return value - will be copied

void post(std::function<void()>&& handler)

Post a handler to the io_context with the guarantee that it is not executed before any other handler posted before has finished. Handlers posted on different Strands can always be run in parallel.

Note that "guaranteeToRun" flag of the constructor determines what happens with yet unhandled handlers when the Strand is destructed.

handler : function without arguments and return value as r-value reference - will be moved to avoid a copy

run

void run()

Helper to run one task after another until tasks queue is empty

setContext

void setContext(boost::asio::io_context& ioContext)

Set the context to which the handlers are to be posted.

No concurrency protection: Must be called directly after Strand creation, before it is used.

startRunningIfNeeded

void startRunningIfNeeded()

Helper for post - to be called under protection of m_tasksMutex!

wrap

std::function<void()> wrap(std::function<void()> handler)

This function is used to create a new handler function object that, when invoked, will pass the wrapped handler to the Strand's post function (instead of using dispatch as boost::io_service::strand::wrap does).

handler : The handler to be wrapped. The strand will make a copy of the handler object. Compared to boost::io_service::strand::wrap, the handler signature is much more restricted, i.e. must be void().

Return : A function object that, when invoked, passes the wrapped handler to the Strand's post function.