io_context::strand

Provides serialised handler execution.

class strand

Member Functions

Name	Description
context	Obtain the underlying execution context.
defer	Request the strand to invoke the given function object.
dispatch	Request the strand to invoke the given function object. — (Deprecated: Use asio::dispatch().) Request the strand to invoke the given handler.
on_work_finished	Inform the strand that some work is no longer outstanding.
on_work_started	Inform the strand that it has some outstanding work to do.
post	Request the strand to invoke the given function object. — (Deprecated: Use asio::post().) Request the strand to invoke the given handler and return immediately.
running_in_this_thread	Determine whether the strand is running in the current thread.
strand [constructor]	Constructor.
wrap	(Deprecated: Use asio::bind_executor().) Create a new handler that automatically dispatches the wrapped handler on the strand.
~strand [destructor]	Destructor.

Friends

Name	Description
operator!=	Compare two strands for inequality.
operator==	Compare two strands for equality.

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.

Remarks

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.

Requirements

Header: asio/io_context_strand.hpp

Convenience header: asio.hpp