execution_context

A context for function object execution.

class execution_context :
  noncopyable

Types

Name	Description
id	Class used to uniquely identify a service.
service	Base class for all io_context services.
fork_event	Fork-related event notifications.

Member Functions

Name	Description
notify_fork	Notify the execution_context of a fork-related event.

Protected Member Functions

Name	Description
destroy	Destroys all services in the context.
execution_context	Constructor.
shutdown	Shuts down all services in the context.
~execution_context	Destructor.

Friends

Name	Description
add_service	(Deprecated: Use make_service().) Add a service object to the execution_context.
has_service	Determine if an execution_context contains a specified service type.
make_service	Creates a service object and adds it to the execution_context.
use_service	Obtain the service object corresponding to the given type.

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.

Requirements

Header: asio/execution_context.hpp

Convenience header: asio.hpp