]>
Commit | Line | Data |
---|---|---|
b32b8144 FG |
1 | // |
2 | // execution_context.hpp | |
3 | // ~~~~~~~~~~~~~~~~~~~~~ | |
4 | // | |
92f5a8d4 | 5 | // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
b32b8144 FG |
6 | // |
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) | |
9 | // | |
10 | ||
11 | #ifndef BOOST_ASIO_EXECUTION_CONTEXT_HPP | |
12 | #define BOOST_ASIO_EXECUTION_CONTEXT_HPP | |
13 | ||
14 | #if defined(_MSC_VER) && (_MSC_VER >= 1200) | |
15 | # pragma once | |
16 | #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) | |
17 | ||
18 | #include <boost/asio/detail/config.hpp> | |
19 | #include <cstddef> | |
20 | #include <stdexcept> | |
21 | #include <typeinfo> | |
22 | #include <boost/asio/detail/noncopyable.hpp> | |
23 | #include <boost/asio/detail/variadic_templates.hpp> | |
24 | ||
25 | #include <boost/asio/detail/push_options.hpp> | |
26 | ||
27 | namespace boost { | |
28 | namespace asio { | |
29 | ||
30 | class execution_context; | |
31 | class io_context; | |
32 | ||
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) | |
39 | ||
40 | namespace detail { class service_registry; } | |
41 | ||
42 | /// A context for function object execution. | |
43 | /** | |
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. | |
46 | * | |
47 | * @par The execution_context class and services | |
48 | * | |
49 | * Class execution_context implements an extensible, type-safe, polymorphic set | |
50 | * of services, indexed by service type. | |
51 | * | |
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. | |
55 | * | |
56 | * Access to the services of an execution_context is via three function | |
57 | * templates, use_service(), add_service() and has_service(). | |
58 | * | |
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>(). | |
65 | * | |
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. | |
71 | * | |
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. | |
75 | * | |
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. | |
79 | * | |
80 | * @par The execution_context as a base class | |
81 | * | |
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 | |
84 | * type. | |
85 | * | |
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>. | |
89 | * | |
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: | |
95 | * | |
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. | |
99 | * | |
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 | |
104 | * destroyed. | |
105 | */ | |
106 | class execution_context | |
107 | : private noncopyable | |
108 | { | |
109 | public: | |
110 | class id; | |
111 | class service; | |
112 | ||
92f5a8d4 | 113 | public: |
b32b8144 FG |
114 | /// Constructor. |
115 | BOOST_ASIO_DECL execution_context(); | |
116 | ||
117 | /// Destructor. | |
118 | BOOST_ASIO_DECL ~execution_context(); | |
119 | ||
92f5a8d4 | 120 | protected: |
b32b8144 FG |
121 | /// Shuts down all services in the context. |
122 | /** | |
123 | * This function is implemented as follows: | |
124 | * | |
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 | |
127 | * svc->shutdown(). | |
128 | */ | |
129 | BOOST_ASIO_DECL void shutdown(); | |
130 | ||
131 | /// Destroys all services in the context. | |
132 | /** | |
133 | * This function is implemented as follows: | |
134 | * | |
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>. | |
138 | */ | |
139 | BOOST_ASIO_DECL void destroy(); | |
140 | ||
141 | public: | |
142 | /// Fork-related event notifications. | |
143 | enum fork_event | |
144 | { | |
145 | /// Notify the context that the process is about to fork. | |
146 | fork_prepare, | |
147 | ||
148 | /// Notify the context that the process has forked and is the parent. | |
149 | fork_parent, | |
150 | ||
151 | /// Notify the context that the process has forked and is the child. | |
152 | fork_child | |
153 | }; | |
154 | ||
155 | /// Notify the execution_context of a fork-related event. | |
156 | /** | |
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. | |
161 | * | |
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. | |
167 | * | |
168 | * @param event A fork-related event. | |
169 | * | |
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 | |
172 | * destroyed. | |
173 | * | |
174 | * @par Example | |
175 | * The following code illustrates how to incorporate the notify_fork() | |
176 | * function: | |
177 | * @code my_execution_context.notify_fork(execution_context::fork_prepare); | |
178 | * if (fork() == 0) | |
179 | * { | |
180 | * // This is the child process. | |
181 | * my_execution_context.notify_fork(execution_context::fork_child); | |
182 | * } | |
183 | * else | |
184 | * { | |
185 | * // This is the parent process. | |
186 | * my_execution_context.notify_fork(execution_context::fork_parent); | |
187 | * } @endcode | |
188 | * | |
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. | |
194 | */ | |
195 | BOOST_ASIO_DECL void notify_fork(fork_event event); | |
196 | ||
197 | /// Obtain the service object corresponding to the given type. | |
198 | /** | |
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. | |
202 | * | |
203 | * @param e The execution_context object that owns the service. | |
204 | * | |
205 | * @return The service interface implementing the specified service type. | |
206 | * Ownership of the service interface is not transferred to the caller. | |
207 | */ | |
208 | template <typename Service> | |
209 | friend Service& use_service(execution_context& e); | |
210 | ||
211 | /// Obtain the service object corresponding to the given type. | |
212 | /** | |
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. | |
216 | * | |
217 | * @param ioc The io_context object that owns the service. | |
218 | * | |
219 | * @return The service interface implementing the specified service type. | |
220 | * Ownership of the service interface is not transferred to the caller. | |
221 | * | |
222 | * @note This overload is preserved for backwards compatibility with services | |
223 | * that inherit from io_context::service. | |
224 | */ | |
225 | template <typename Service> | |
226 | friend Service& use_service(io_context& ioc); | |
227 | ||
228 | #if defined(GENERATING_DOCUMENTATION) | |
229 | ||
230 | /// Creates a service object and adds it to the execution_context. | |
231 | /** | |
232 | * This function is used to add a service to the execution_context. | |
233 | * | |
234 | * @param e The execution_context object that owns the service. | |
235 | * | |
236 | * @param args Zero or more arguments to be passed to the service | |
237 | * constructor. | |
238 | * | |
239 | * @throws boost::asio::service_already_exists Thrown if a service of the | |
240 | * given type is already present in the execution_context. | |
241 | */ | |
242 | template <typename Service, typename... Args> | |
243 | friend Service& make_service(execution_context& e, Args&&... args); | |
244 | ||
245 | #elif defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) | |
246 | ||
247 | template <typename Service, typename... Args> | |
248 | friend Service& make_service(execution_context& e, | |
249 | BOOST_ASIO_MOVE_ARG(Args)... args); | |
250 | ||
251 | #else // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) | |
252 | ||
253 | template <typename Service> | |
254 | friend Service& make_service(execution_context& e); | |
255 | ||
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)); \ | |
260 | /**/ | |
261 | BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF) | |
262 | #undef BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF | |
263 | ||
264 | #endif // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES) | |
265 | ||
266 | /// (Deprecated: Use make_service().) Add a service object to the | |
267 | /// execution_context. | |
268 | /** | |
269 | * This function is used to add a service to the execution_context. | |
270 | * | |
271 | * @param e The execution_context object that owns the service. | |
272 | * | |
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 | |
277 | * | |
278 | * @throws boost::asio::service_already_exists Thrown if a service of the | |
279 | * given type is already present in the execution_context. | |
280 | * | |
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 | |
283 | * @c e parameter. | |
284 | */ | |
285 | template <typename Service> | |
286 | friend void add_service(execution_context& e, Service* svc); | |
287 | ||
288 | /// Determine if an execution_context contains a specified service type. | |
289 | /** | |
290 | * This function is used to determine whether the execution_context contains a | |
291 | * service object corresponding to the given service type. | |
292 | * | |
293 | * @param e The execution_context object that owns the service. | |
294 | * | |
295 | * @return A boolean indicating whether the execution_context contains the | |
296 | * service. | |
297 | */ | |
298 | template <typename Service> | |
299 | friend bool has_service(execution_context& e); | |
300 | ||
301 | private: | |
302 | // The service registry. | |
303 | boost::asio::detail::service_registry* service_registry_; | |
304 | }; | |
305 | ||
306 | /// Class used to uniquely identify a service. | |
307 | class execution_context::id | |
308 | : private noncopyable | |
309 | { | |
310 | public: | |
311 | /// Constructor. | |
312 | id() {} | |
313 | }; | |
314 | ||
315 | /// Base class for all io_context services. | |
316 | class execution_context::service | |
317 | : private noncopyable | |
318 | { | |
319 | public: | |
320 | /// Get the context object that owns the service. | |
321 | execution_context& context(); | |
322 | ||
323 | protected: | |
324 | /// Constructor. | |
325 | /** | |
326 | * @param owner The execution_context object that owns the service. | |
327 | */ | |
328 | BOOST_ASIO_DECL service(execution_context& owner); | |
329 | ||
330 | /// Destructor. | |
331 | BOOST_ASIO_DECL virtual ~service(); | |
332 | ||
333 | private: | |
334 | /// Destroy all user-defined handler objects owned by the service. | |
335 | virtual void shutdown() = 0; | |
336 | ||
337 | /// Handle notification of a fork-related event to perform any necessary | |
338 | /// housekeeping. | |
339 | /** | |
340 | * This function is not a pure virtual so that services only have to | |
341 | * implement it if necessary. The default implementation does nothing. | |
342 | */ | |
343 | BOOST_ASIO_DECL virtual void notify_fork( | |
344 | execution_context::fork_event event); | |
345 | ||
346 | friend class boost::asio::detail::service_registry; | |
347 | struct key | |
348 | { | |
349 | key() : type_info_(0), id_(0) {} | |
350 | const std::type_info* type_info_; | |
351 | const execution_context::id* id_; | |
352 | } key_; | |
353 | ||
354 | execution_context& owner_; | |
355 | service* next_; | |
356 | }; | |
357 | ||
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 | |
362 | { | |
363 | public: | |
364 | BOOST_ASIO_DECL service_already_exists(); | |
365 | }; | |
366 | ||
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 | |
371 | { | |
372 | public: | |
373 | BOOST_ASIO_DECL invalid_service_owner(); | |
374 | }; | |
375 | ||
376 | namespace detail { | |
377 | ||
378 | // Special derived service id type to keep classes header-file only. | |
379 | template <typename Type> | |
380 | class service_id | |
381 | : public execution_context::id | |
382 | { | |
383 | }; | |
384 | ||
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 | |
389 | { | |
390 | public: | |
391 | static service_id<Type> id; | |
392 | ||
393 | // Constructor. | |
394 | execution_context_service_base(execution_context& e) | |
395 | : execution_context::service(e) | |
396 | { | |
397 | } | |
398 | }; | |
399 | ||
400 | template <typename Type> | |
401 | service_id<Type> execution_context_service_base<Type>::id; | |
402 | ||
403 | } // namespace detail | |
404 | } // namespace asio | |
405 | } // namespace boost | |
406 | ||
407 | #include <boost/asio/detail/pop_options.hpp> | |
408 | ||
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) | |
413 | ||
414 | #endif // BOOST_ASIO_EXECUTION_CONTEXT_HPP |