2 // execution_context.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
11 #ifndef BOOST_ASIO_EXECUTION_CONTEXT_HPP
12 #define BOOST_ASIO_EXECUTION_CONTEXT_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
22 #include <boost/asio/detail/noncopyable.hpp>
23 #include <boost/asio/detail/variadic_templates.hpp>
25 #include <boost/asio/detail/push_options.hpp>
30 class execution_context;
33 #if !defined(GENERATING_DOCUMENTATION)
34 template <typename Service> Service& use_service(execution_context&);
35 template <typename Service> Service& use_service(io_context&);
36 template <typename Service> void add_service(execution_context&, Service*);
37 template <typename Service> bool has_service(execution_context&);
38 #endif // !defined(GENERATING_DOCUMENTATION)
40 namespace detail { class service_registry; }
42 /// A context for function object execution.
44 * An execution context represents a place where function objects will be
45 * executed. An @c io_context is an example of an execution context.
47 * @par The execution_context class and services
49 * Class execution_context implements an extensible, type-safe, polymorphic set
50 * of services, indexed by service type.
52 * Services exist to manage the resources that are shared across an execution
53 * context. For example, timers may be implemented in terms of a single timer
54 * queue, and this queue would be stored in a service.
56 * Access to the services of an execution_context is via three function
57 * templates, use_service(), add_service() and has_service().
59 * In a call to @c use_service<Service>(), the type argument chooses a service,
60 * making available all members of the named type. If @c Service is not present
61 * in an execution_context, an object of type @c Service is created and added
62 * to the execution_context. A C++ program can check if an execution_context
63 * implements a particular service with the function template @c
64 * has_service<Service>().
66 * Service objects may be explicitly added to an execution_context using the
67 * function template @c add_service<Service>(). If the @c Service is already
68 * present, the service_already_exists exception is thrown. If the owner of the
69 * service is not the same object as the execution_context parameter, the
70 * invalid_service_owner exception is thrown.
72 * Once a service reference is obtained from an execution_context object by
73 * calling use_service(), that reference remains usable as long as the owning
74 * execution_context object exists.
76 * All service implementations have execution_context::service as a public base
77 * class. Custom services may be implemented by deriving from this class and
78 * then added to an execution_context using the facilities described above.
80 * @par The execution_context as a base class
82 * Class execution_context may be used only as a base class for concrete
83 * execution context types. The @c io_context is an example of such a derived
86 * On destruction, a class that is derived from execution_context must perform
87 * <tt>execution_context::shutdown()</tt> followed by
88 * <tt>execution_context::destroy()</tt>.
90 * This destruction sequence permits programs to simplify their resource
91 * management by using @c shared_ptr<>. Where an object's lifetime is tied to
92 * the lifetime of a connection (or some other sequence of asynchronous
93 * operations), a @c shared_ptr to the object would be bound into the handlers
94 * for all asynchronous operations associated with it. This works as follows:
96 * @li When a single connection ends, all associated asynchronous operations
97 * complete. The corresponding handler objects are destroyed, and all @c
98 * shared_ptr references to the objects are destroyed.
100 * @li To shut down the whole program, the io_context function stop() is called
101 * to terminate any run() calls as soon as possible. The io_context destructor
102 * calls @c shutdown() and @c destroy() to destroy all pending handlers,
103 * causing all @c shared_ptr references to all connection objects to be
106 class execution_context
107 : private noncopyable
115 BOOST_ASIO_DECL execution_context();
118 BOOST_ASIO_DECL ~execution_context();
121 /// Shuts down all services in the context.
123 * This function is implemented as follows:
125 * @li For each service object @c svc in the execution_context set, in
126 * reverse order of the beginning of service object lifetime, performs @c
129 BOOST_ASIO_DECL void shutdown();
131 /// Destroys all services in the context.
133 * This function is implemented as follows:
135 * @li For each service object @c svc in the execution_context set, in
136 * reverse order * of the beginning of service object lifetime, performs
137 * <tt>delete static_cast<execution_context::service*>(svc)</tt>.
139 BOOST_ASIO_DECL void destroy();
142 /// Fork-related event notifications.
145 /// Notify the context that the process is about to fork.
148 /// Notify the context that the process has forked and is the parent.
151 /// Notify the context that the process has forked and is the child.
155 /// Notify the execution_context of a fork-related event.
157 * This function is used to inform the execution_context that the process is
158 * about to fork, or has just forked. This allows the execution_context, and
159 * the services it contains, to perform any necessary housekeeping to ensure
160 * correct operation following a fork.
162 * This function must not be called while any other execution_context
163 * function, or any function associated with the execution_context's derived
164 * class, is being called in another thread. It is, however, safe to call
165 * this function from within a completion handler, provided no other thread
166 * is accessing the execution_context or its derived class.
168 * @param event A fork-related event.
170 * @throws boost::system::system_error Thrown on failure. If the notification
171 * fails the execution_context object should no longer be used and should be
175 * The following code illustrates how to incorporate the notify_fork()
177 * @code my_execution_context.notify_fork(execution_context::fork_prepare);
180 * // This is the child process.
181 * my_execution_context.notify_fork(execution_context::fork_child);
185 * // This is the parent process.
186 * my_execution_context.notify_fork(execution_context::fork_parent);
189 * @note For each service object @c svc in the execution_context set,
190 * performs <tt>svc->notify_fork();</tt>. When processing the fork_prepare
191 * event, services are visited in reverse order of the beginning of service
192 * object lifetime. Otherwise, services are visited in order of the beginning
193 * of service object lifetime.
195 BOOST_ASIO_DECL void notify_fork(fork_event event);
197 /// Obtain the service object corresponding to the given type.
199 * This function is used to locate a service object that corresponds to the
200 * given service type. If there is no existing implementation of the service,
201 * then the execution_context will create a new instance of the service.
203 * @param e The execution_context object that owns the service.
205 * @return The service interface implementing the specified service type.
206 * Ownership of the service interface is not transferred to the caller.
208 template <typename Service>
209 friend Service& use_service(execution_context& e);
211 /// Obtain the service object corresponding to the given type.
213 * This function is used to locate a service object that corresponds to the
214 * given service type. If there is no existing implementation of the service,
215 * then the io_context will create a new instance of the service.
217 * @param ioc The io_context object that owns the service.
219 * @return The service interface implementing the specified service type.
220 * Ownership of the service interface is not transferred to the caller.
222 * @note This overload is preserved for backwards compatibility with services
223 * that inherit from io_context::service.
225 template <typename Service>
226 friend Service& use_service(io_context& ioc);
228 #if defined(GENERATING_DOCUMENTATION)
230 /// Creates a service object and adds it to the execution_context.
232 * This function is used to add a service to the execution_context.
234 * @param e The execution_context object that owns the service.
236 * @param args Zero or more arguments to be passed to the service
239 * @throws boost::asio::service_already_exists Thrown if a service of the
240 * given type is already present in the execution_context.
242 template <typename Service, typename... Args>
243 friend Service& make_service(execution_context& e, Args&&... args);
245 #elif defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
247 template <typename Service, typename... Args>
248 friend Service& make_service(execution_context& e,
249 BOOST_ASIO_MOVE_ARG(Args)... args);
251 #else // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
253 template <typename Service>
254 friend Service& make_service(execution_context& e);
256 #define BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF(n) \
257 template <typename Service, BOOST_ASIO_VARIADIC_TPARAMS(n)> \
258 friend Service& make_service(execution_context& e, \
259 BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)); \
261 BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF)
262 #undef BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF
264 #endif // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
266 /// (Deprecated: Use make_service().) Add a service object to the
267 /// execution_context.
269 * This function is used to add a service to the execution_context.
271 * @param e The execution_context object that owns the service.
273 * @param svc The service object. On success, ownership of the service object
274 * is transferred to the execution_context. When the execution_context object
275 * is destroyed, it will destroy the service object by performing: @code
276 * delete static_cast<execution_context::service*>(svc) @endcode
278 * @throws boost::asio::service_already_exists Thrown if a service of the
279 * given type is already present in the execution_context.
281 * @throws boost::asio::invalid_service_owner Thrown if the service's owning
282 * execution_context is not the execution_context object specified by the
285 template <typename Service>
286 friend void add_service(execution_context& e, Service* svc);
288 /// Determine if an execution_context contains a specified service type.
290 * This function is used to determine whether the execution_context contains a
291 * service object corresponding to the given service type.
293 * @param e The execution_context object that owns the service.
295 * @return A boolean indicating whether the execution_context contains the
298 template <typename Service>
299 friend bool has_service(execution_context& e);
302 // The service registry.
303 boost::asio::detail::service_registry* service_registry_;
306 /// Class used to uniquely identify a service.
307 class execution_context::id
308 : private noncopyable
315 /// Base class for all io_context services.
316 class execution_context::service
317 : private noncopyable
320 /// Get the context object that owns the service.
321 execution_context& context();
326 * @param owner The execution_context object that owns the service.
328 BOOST_ASIO_DECL service(execution_context& owner);
331 BOOST_ASIO_DECL virtual ~service();
334 /// Destroy all user-defined handler objects owned by the service.
335 virtual void shutdown() = 0;
337 /// Handle notification of a fork-related event to perform any necessary
340 * This function is not a pure virtual so that services only have to
341 * implement it if necessary. The default implementation does nothing.
343 BOOST_ASIO_DECL virtual void notify_fork(
344 execution_context::fork_event event);
346 friend class boost::asio::detail::service_registry;
349 key() : type_info_(0), id_(0) {}
350 const std::type_info* type_info_;
351 const execution_context::id* id_;
354 execution_context& owner_;
358 /// Exception thrown when trying to add a duplicate service to an
359 /// execution_context.
360 class service_already_exists
361 : public std::logic_error
364 BOOST_ASIO_DECL service_already_exists();
367 /// Exception thrown when trying to add a service object to an
368 /// execution_context where the service has a different owner.
369 class invalid_service_owner
370 : public std::logic_error
373 BOOST_ASIO_DECL invalid_service_owner();
378 // Special derived service id type to keep classes header-file only.
379 template <typename Type>
381 : public execution_context::id
385 // Special service base class to keep classes header-file only.
386 template <typename Type>
387 class execution_context_service_base
388 : public execution_context::service
391 static service_id<Type> id;
394 execution_context_service_base(execution_context& e)
395 : execution_context::service(e)
400 template <typename Type>
401 service_id<Type> execution_context_service_base<Type>::id;
403 } // namespace detail
407 #include <boost/asio/detail/pop_options.hpp>
409 #include <boost/asio/impl/execution_context.hpp>
410 #if defined(BOOST_ASIO_HEADER_ONLY)
411 # include <boost/asio/impl/execution_context.ipp>
412 #endif // defined(BOOST_ASIO_HEADER_ONLY)
414 #endif // BOOST_ASIO_EXECUTION_CONTEXT_HPP