| Home | Libraries | People | FAQ | More

### 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
--- | ---
execution_context | Constructor.
notify_fork | Notify the execution_context of a fork-related event.
~execution_context | Destructor.

##### Protected Member Functions

Name | Description
--- | ---
destroy | Destroys all services in the context.
shutdown | Shuts down all services in the context.

##### 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: `boost/asio/execution_context.hpp`

Convenience header: `boost/asio.hpp`