asio::execution_context Class Reference

A context for function object execution. More...

#include <execution_context.hpp>

Inheritance diagram for asio::execution_context:

Collaboration diagram for asio::execution_context:

Classes
class	id
	Class used to uniquely identify a service. More...
class	service
	Base class for all io_context services. More...

Public Types
enum	fork_event { fork_prepare, fork_parent, fork_child }
	Fork-related event notifications. More...

Public Member Functions
ASIO_DECL	execution_context ()
	Constructor.
ASIO_DECL	~execution_context ()
	Destructor.
ASIO_DECL void	notify_fork (fork_event event)
	Notify the execution_context of a fork-related event. More...

Protected Member Functions
ASIO_DECL void	shutdown ()
	Shuts down all services in the context. More...
ASIO_DECL void	destroy ()
	Destroys all services in the context. More...

Friends
template<typename Service >
Service &	use_service (execution_context &e)
	Obtain the service object corresponding to the given type. More...
template<typename Service >
Service &	use_service (io_context &ioc)
	Obtain the service object corresponding to the given type. More...
template<typename Service >
Service &	make_service (execution_context &e)
template<typename Service >
void	add_service (execution_context &e, Service *svc)
	(Deprecated: Use make_service().) Add a service object to the execution_context. More...
template<typename Service >
bool	has_service (execution_context &e)
	Determine if an execution_context contains a specified service type. More...

Detailed Description

A context for function object execution.

An execution context represents a place where function objects will be executed. An io_context is an example of an execution context.

The execution_context class and services

Class execution_context implements an extensible, type-safe, polymorphic set of services, indexed by service type.

Services exist to manage the resources that are shared across an execution context. For example, timers may be implemented in terms of a single timer queue, and this queue would be stored in a service.

Access to the services of an execution_context is via three function templates, use_service(), add_service() and has_service().

In a call to use_service<Service>(), the type argument chooses a service, making available all members of the named type. If Service is not present in an execution_context, an object of type Service is created and added to the execution_context. A C++ program can check if an execution_context implements a particular service with the function template has_service<Service>().

Service objects may be explicitly added to an execution_context using the function template add_service<Service>(). If the Service is already present, the service_already_exists exception is thrown. If the owner of the service is not the same object as the execution_context parameter, the invalid_service_owner exception is thrown.

Once a service reference is obtained from an execution_context object by calling use_service(), that reference remains usable as long as the owning execution_context object exists.

All service implementations have execution_context::service as a public base class. Custom services may be implemented by deriving from this class and then added to an execution_context using the facilities described above.

The execution_context as a base class

Class execution_context may be used only as a base class for concrete execution context types. The io_context is an example of such a derived type.

On destruction, a class that is derived from execution_context must perform execution_context::shutdown() followed by execution_context::destroy().

This destruction sequence permits programs to simplify their resource management by using shared_ptr<>. Where an object's lifetime is tied to the lifetime of a connection (or some other sequence of asynchronous operations), a shared_ptr to the object would be bound into the handlers for all asynchronous operations associated with it. This works as follows:

• When a single connection ends, all associated asynchronous operations complete. The corresponding handler objects are destroyed, and all shared_ptr references to the objects are destroyed.

• To shut down the whole program, the io_context function stop() is called to terminate any run() calls as soon as possible. The io_context destructor calls shutdown() and destroy() to destroy all pending handlers, causing all shared_ptr references to all connection objects to be destroyed.

Member Enumeration Documentation

fork_event

enum asio::execution_context::fork_event

Fork-related event notifications.

Enumerator
fork_prepare	Notify the context that the process is about to fork.
fork_parent	Notify the context that the process has forked and is the parent.
fork_child	Notify the context that the process has forked and is the child.

Member Function Documentation

destroy()

void execution_context::destroy ( )

protected

Destroys all services in the context.

This function is implemented as follows:

• For each service object svc in the execution_context set, in reverse order * of the beginning of service object lifetime, performs delete static_cast<execution_context::service*>(svc).

notify_fork()

void execution_context::notify_fork

(

fork_event

event

)

Notify the execution_context of a fork-related event.

This function is used to inform the execution_context that the process is about to fork, or has just forked. This allows the execution_context, and the services it contains, to perform any necessary housekeeping to ensure correct operation following a fork.

This function must not be called while any other execution_context function, or any function associated with the execution_context's derived class, is being called in another thread. It is, however, safe to call this function from within a completion handler, provided no other thread is accessing the execution_context or its derived class.

Parameters

event

A fork-related event.

Exceptions

asio::system_error

Thrown on failure. If the notification fails the execution_context object should no longer be used and should be destroyed.

Example

The following code illustrates how to incorporate the notify_fork() function:

 my_execution_context.notify_fork(execution_context::fork_prepare);
if (fork() == 0)
{
  // This is the child process.
  my_execution_context.notify_fork(execution_context::fork_child);
}
else
{
  // This is the parent process.
  my_execution_context.notify_fork(execution_context::fork_parent);
} 

Note

For each service object svc in the execution_context set, performs svc->notify_fork();. When processing the fork_prepare event, services are visited in reverse order of the beginning of service object lifetime. Otherwise, services are visited in order of the beginning of service object lifetime.

shutdown()

void execution_context::shutdown ( )

protected

Shuts down all services in the context.

This function is implemented as follows:

• For each service object svc in the execution_context set, in reverse order of the beginning of service object lifetime, performs svc->shutdown().

Friends And Related Function Documentation

add_service

template<typename Service >

void add_service ( execution_context &  e, Service *  svc  )

friend

(Deprecated: Use make_service().) Add a service object to the execution_context.

This function is used to add a service to the execution_context.

Parameters

e	The execution_context object that owns the service.
svc	The service object. On success, ownership of the service object is transferred to the execution_context. When the execution_context object is destroyed, it will destroy the service object by performing: delete static_cast<execution_context::service*>(svc)

Exceptions

asio::service_already_exists	Thrown if a service of the given type is already present in the execution_context.
asio::invalid_service_owner	Thrown if the service's owning execution_context is not the execution_context object specified by the e parameter.

has_service

template<typename Service >

bool has_service ( execution_context &  e )

friend

Determine if an execution_context contains a specified service type.

This function is used to determine whether the execution_context contains a service object corresponding to the given service type.

Parameters

e	The execution_context object that owns the service.

Returns

A boolean indicating whether the execution_context contains the service.

use_service [1/2]

template<typename Service >

Service& use_service ( execution_context &  e )

friend

Obtain the service object corresponding to the given type.

This function is used to locate a service object that corresponds to the given service type. If there is no existing implementation of the service, then the execution_context will create a new instance of the service.

Parameters

e	The execution_context object that owns the service.

Returns

The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.

use_service [2/2]

template<typename Service >

Service& use_service ( io_context &  ioc )

friend

Obtain the service object corresponding to the given type.

This function is used to locate a service object that corresponds to the given service type. If there is no existing implementation of the service, then the io_context will create a new instance of the service.

Parameters

ioc	The io_context object that owns the service.

Returns

The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.

Note

This overload is preserved for backwards compatibility with services that inherit from io_context::service.

---

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

• Thirdparty/asio/include/asio/execution_context.hpp
• Thirdparty/asio/include/asio/impl/execution_context.ipp