Provides serialised handler execution. More...

#include <io_context_strand.hpp>

Public Member Functions
	strand (asio::io_context &io_context)
	Constructor. More...

	~strand ()
	Destructor. More...

asio::io_context &	context () const ASIO_NOEXCEPT
	Obtain the underlying execution context.

void	on_work_started () const ASIO_NOEXCEPT
	Inform the strand that it has some outstanding work to do. More...

void	on_work_finished () const ASIO_NOEXCEPT
	Inform the strand that some work is no longer outstanding. More...

template<typename Function , typename Allocator >
void	dispatch (ASIO_MOVE_ARG(Function) f, const Allocator &a) const
	Request the strand to invoke the given function object. More...

template<typename LegacyCompletionHandler >
	dispatch (ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
	(Deprecated: Use asio::dispatch().) Request the strand to invoke the given handler. More...

template<typename Function , typename Allocator >
void	post (ASIO_MOVE_ARG(Function) f, const Allocator &a) const
	Request the strand to invoke the given function object. More...

template<typename LegacyCompletionHandler >
	post (ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
	(Deprecated: Use asio::post().) Request the strand to invoke the given handler and return immediately. More...

template<typename Function , typename Allocator >
void	defer (ASIO_MOVE_ARG(Function) f, const Allocator &a) const
	Request the strand to invoke the given function object. More...

template<typename Handler >
detail::wrapped_handler< strand, Handler, detail::is_continuation_if_running >	wrap (Handler handler)
	(Deprecated: Use asio::bind_executor().) Create a new handler that automatically dispatches the wrapped handler on the strand. More...

bool	running_in_this_thread () const ASIO_NOEXCEPT
	Determine whether the strand is running in the current thread. More...

Friends
bool	operator== (const strand &a, const strand &b) ASIO_NOEXCEPT
	Compare two strands for equality. More...

bool	operator!= (const strand &a, const strand &b) ASIO_NOEXCEPT
	Compare two strands for inequality. More...

Detailed Description

Provides serialised handler execution.

The io_context::strand class provides the ability to post and dispatch handlers with the guarantee that none of those handlers will execute concurrently.

Order of handler invocation: Given:

a strand object s

an object a meeting completion handler requirements

an object a1 which is an arbitrary copy of a made by the implementation

an object b meeting completion handler requirements

an object b1 which is an arbitrary copy of b made by the implementation

if any of the following conditions are true:

s.post(a) happens-before s.post(b)

s.post(a) happens-before s.dispatch(b), where the latter is performed outside the strand

s.dispatch(a) happens-before s.post(b), where the former is performed outside the strand

s.dispatch(a) happens-before s.dispatch(b), where both are performed outside the strand

then asio_handler_invoke(a1, &a1) happens-before asio_handler_invoke(b1, &b1).

Note that in the following case:

async_op_1(..., s.wrap(a));

async_op_2(..., s.wrap(b));

the completion of the first async operation will perform s.dispatch(a), and the second will perform s.dispatch(b), but the order in which those are performed is unspecified. That is, you cannot state whether one happens-before the other. Therefore none of the above conditions are met and no ordering guarantee is made.

Note: The implementation makes no guarantee that handlers posted or dispatched through different strand objects will be invoked concurrently.

Thread Safety: Distinct objects: Safe.
Shared objects: Safe.

Concepts:: Dispatcher.

Constructor & Destructor Documentation

◆ strand()

asio::io_context::strand::strand ( asio::io_context & io_context )

inlineexplicit

Constructor.

Constructs the strand.

Parameters

io_context The io_context object that the strand will use to dispatch handlers that are ready to be run.

◆ ~strand()

asio::io_context::strand::~strand ( )

inline

Destructor.

Destroys a strand.

Handlers posted through the strand that have not yet been invoked will still be dispatched in a way that meets the guarantee of non-concurrency.

Member Function Documentation

◆ defer()

template<typename Function , typename Allocator >

void asio::io_context::strand::defer	(	ASIO_MOVE_ARG(Function)	f,
		const Allocator &	a
	)		const

inline

Request the strand to invoke the given function object.

This function is used to ask the executor to execute the given function object. The function object will never be executed inside this function. Instead, it will be scheduled to run by the underlying io_context.

Parameters

f	The function object to be called. The executor will make a copy of the handler object as required. The function signature of the function object must be: void function();
a	An allocator that may be used by the executor to allocate the internal storage needed for function invocation.

◆ dispatch() [1/2]

template<typename Function , typename Allocator >

void asio::io_context::strand::dispatch	(	ASIO_MOVE_ARG(Function)	f,
		const Allocator &	a
	)		const

inline

Request the strand to invoke the given function object.

This function is used to ask the strand to execute the given function object on its underlying io_context. The function object will be executed inside this function if the strand is not otherwise busy and if the underlying io_context's executor's dispatch() function is also able to execute the function before returning.

Parameters

f	The function object to be called. The executor will make a copy of the handler object as required. The function signature of the function object must be: void function();
a	An allocator that may be used by the executor to allocate the internal storage needed for function invocation.

◆ dispatch() [2/2]

template<typename LegacyCompletionHandler >

asio::io_context::strand::dispatch ( ASIO_MOVE_ARG(LegacyCompletionHandler) handler )

inline

(Deprecated: Use asio::dispatch().) Request the strand to invoke the given handler.

This function is used to ask the strand to execute the given handler.

The strand object guarantees that handlers posted or dispatched through the strand will not be executed concurrently. The handler may be executed inside this function if the guarantee can be met. If this function is called from within a handler that was posted or dispatched through the same strand, then the new handler will be executed immediately.

The strand's guarantee is in addition to the guarantee provided by the underlying io_context. The io_context guarantees that the handler will only be called in a thread in which the io_context's run member function is currently being invoked.

Parameters

handler

The handler to be called. The strand will make a copy of the handler object as required. The function signature of the handler must be:

void handler();

◆ on_work_finished()

void asio::io_context::strand::on_work_finished ( ) const

inline

Inform the strand that some work is no longer outstanding.

The strand delegates this call to its underlying io_context.

◆ on_work_started()

void asio::io_context::strand::on_work_started ( ) const

inline

Inform the strand that it has some outstanding work to do.

The strand delegates this call to its underlying io_context.

◆ post() [1/2]

template<typename Function , typename Allocator >

void asio::io_context::strand::post	(	ASIO_MOVE_ARG(Function)	f,
		const Allocator &	a
	)		const

inline

Request the strand to invoke the given function object.

This function is used to ask the executor to execute the given function object. The function object will never be executed inside this function. Instead, it will be scheduled to run by the underlying io_context.

Parameters

f	The function object to be called. The executor will make a copy of the handler object as required. The function signature of the function object must be: void function();
a	An allocator that may be used by the executor to allocate the internal storage needed for function invocation.

◆ post() [2/2]

template<typename LegacyCompletionHandler >

asio::io_context::strand::post ( ASIO_MOVE_ARG(LegacyCompletionHandler) handler )

inline

(Deprecated: Use asio::post().) Request the strand to invoke the given handler and return immediately.

This function is used to ask the strand to execute the given handler, but without allowing the strand to call the handler from inside this function.

The strand object guarantees that handlers posted or dispatched through the strand will not be executed concurrently. The strand's guarantee is in addition to the guarantee provided by the underlying io_context. The io_context guarantees that the handler will only be called in a thread in which the io_context's run member function is currently being invoked.

Parameters

handler

The handler to be called. The strand will make a copy of the handler object as required. The function signature of the handler must be:

void handler();

◆ running_in_this_thread()

bool asio::io_context::strand::running_in_this_thread ( ) const

inline

Determine whether the strand is running in the current thread.

Returns: true if the current thread is executing a handler that was submitted to the strand using post(), dispatch() or wrap(). Otherwise returns false.

◆ wrap()

template<typename Handler >

detail::wrapped_handler<strand, Handler, detail::is_continuation_if_running> asio::io_context::strand::wrap ( Handler handler )

inline

(Deprecated: Use asio::bind_executor().) Create a new handler that automatically dispatches the wrapped handler on the strand.

This function is used to create a new handler function object that, when invoked, will automatically pass the wrapped handler to the strand's dispatch function.

Parameters

handler

The handler to be wrapped. The strand will make a copy of the handler object as required. The function signature of the handler must be:

void handler(A1 a1, ... An an);

Returns: A function object that, when invoked, passes the wrapped handler to the strand's dispatch function. Given a function object with the signature:
R f(A1 a1, ... An an);
If this function object is passed to the wrap function like so:
strand.wrap(f);
then the return value is a function object with the signature
void g(A1 a1, ... An an);
that, when invoked, executes code equivalent to:
strand.dispatch(boost::bind(f, a1, ... an));

Friends And Related Function Documentation

◆ operator!=

bool operator!=	(	const strand &	a,
		const strand &	b
	)

friend

Compare two strands for inequality.

Two strands are equal if they refer to the same ordered, non-concurrent state.

◆ operator==

bool operator==	(	const strand &	a,
		const strand &	b
	)

friend

Compare two strands for equality.

Two strands are equal if they refer to the same ordered, non-concurrent state.

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

Thirdparty/asio/include/asio/io_context_strand.hpp

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ strand()

◆ ~strand()

Member Function Documentation

◆ defer()

◆ dispatch() [1/2]

◆ dispatch() [2/2]

◆ on_work_finished()

◆ on_work_started()

◆ post() [1/2]

◆ post() [2/2]

◆ running_in_this_thread()

◆ wrap()

Friends And Related Function Documentation

◆ operator!=

◆ operator==