ceph/src/boost/boost/asio/execution_context.hpp

   1 //
   2 // execution_context.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2018 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   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
 113 protected:
 114   /// Constructor.
 115   BOOST_ASIO_DECL execution_context();
 116
 117   /// Destructor.
 118   BOOST_ASIO_DECL ~execution_context();
 119
 120   /// Shuts down all services in the context.
 121   /**
 122    * This function is implemented as follows:
 123    *
 124    * @li For each service object @c svc in the execution_context set, in
 125    * reverse order of the beginning of service object lifetime, performs @c
 126    * svc->shutdown().
 127    */
 128   BOOST_ASIO_DECL void shutdown();
 129
 130   /// Destroys all services in the context.
 131   /**
 132    * This function is implemented as follows:
 133    *
 134    * @li For each service object @c svc in the execution_context set, in
 135    * reverse order * of the beginning of service object lifetime, performs
 136    * <tt>delete static_cast<execution_context::service*>(svc)</tt>.
 137    */
 138   BOOST_ASIO_DECL void destroy();
 139
 140 public:
 141   /// Fork-related event notifications.
 142   enum fork_event
 143   {
 144     /// Notify the context that the process is about to fork.
 145     fork_prepare,
 146
 147     /// Notify the context that the process has forked and is the parent.
 148     fork_parent,
 149
 150     /// Notify the context that the process has forked and is the child.
 151     fork_child
 152   };
 153
 154   /// Notify the execution_context of a fork-related event.
 155   /**
 156    * This function is used to inform the execution_context that the process is
 157    * about to fork, or has just forked. This allows the execution_context, and
 158    * the services it contains, to perform any necessary housekeeping to ensure
 159    * correct operation following a fork.
 160    *
 161    * This function must not be called while any other execution_context
 162    * function, or any function associated with the execution_context's derived
 163    * class, is being called in another thread. It is, however, safe to call
 164    * this function from within a completion handler, provided no other thread
 165    * is accessing the execution_context or its derived class.
 166    *
 167    * @param event A fork-related event.
 168    *
 169    * @throws boost::system::system_error Thrown on failure. If the notification
 170    * fails the execution_context object should no longer be used and should be
 171    * destroyed.
 172    *
 173    * @par Example
 174    * The following code illustrates how to incorporate the notify_fork()
 175    * function:
 176    * @code my_execution_context.notify_fork(execution_context::fork_prepare);
 177    * if (fork() == 0)
 178    * {
 179    *   // This is the child process.
 180    *   my_execution_context.notify_fork(execution_context::fork_child);
 181    * }
 182    * else
 183    * {
 184    *   // This is the parent process.
 185    *   my_execution_context.notify_fork(execution_context::fork_parent);
 186    * } @endcode
 187    *
 188    * @note For each service object @c svc in the execution_context set,
 189    * performs <tt>svc->notify_fork();</tt>. When processing the fork_prepare
 190    * event, services are visited in reverse order of the beginning of service
 191    * object lifetime. Otherwise, services are visited in order of the beginning
 192    * of service object lifetime.
 193    */
 194   BOOST_ASIO_DECL void notify_fork(fork_event event);
 195
 196   /// Obtain the service object corresponding to the given type.
 197   /**
 198    * This function is used to locate a service object that corresponds to the
 199    * given service type. If there is no existing implementation of the service,
 200    * then the execution_context will create a new instance of the service.
 201    *
 202    * @param e The execution_context object that owns the service.
 203    *
 204    * @return The service interface implementing the specified service type.
 205    * Ownership of the service interface is not transferred to the caller.
 206    */
 207   template <typename Service>
 208   friend Service& use_service(execution_context& e);
 209
 210   /// Obtain the service object corresponding to the given type.
 211   /**
 212    * This function is used to locate a service object that corresponds to the
 213    * given service type. If there is no existing implementation of the service,
 214    * then the io_context will create a new instance of the service.
 215    *
 216    * @param ioc The io_context object that owns the service.
 217    *
 218    * @return The service interface implementing the specified service type.
 219    * Ownership of the service interface is not transferred to the caller.
 220    *
 221    * @note This overload is preserved for backwards compatibility with services
 222    * that inherit from io_context::service.
 223    */
 224   template <typename Service>
 225   friend Service& use_service(io_context& ioc);
 226
 227 #if defined(GENERATING_DOCUMENTATION)
 228
 229   /// Creates a service object and adds it to the execution_context.
 230   /**
 231    * This function is used to add a service to the execution_context.
 232    *
 233    * @param e The execution_context object that owns the service.
 234    *
 235    * @param args Zero or more arguments to be passed to the service
 236    * constructor.
 237    *
 238    * @throws boost::asio::service_already_exists Thrown if a service of the
 239    * given type is already present in the execution_context.
 240    */
 241   template <typename Service, typename... Args>
 242   friend Service& make_service(execution_context& e, Args&&... args);
 243
 244 #elif defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
 245
 246   template <typename Service, typename... Args>
 247   friend Service& make_service(execution_context& e,
 248       BOOST_ASIO_MOVE_ARG(Args)... args);
 249
 250 #else // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
 251
 252   template <typename Service>
 253   friend Service& make_service(execution_context& e);
 254
 255 #define BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF(n) \
 256   template <typename Service, BOOST_ASIO_VARIADIC_TPARAMS(n)> \
 257   friend Service& make_service(execution_context& e, \
 258       BOOST_ASIO_VARIADIC_MOVE_PARAMS(n)); \
 259   /**/
 260   BOOST_ASIO_VARIADIC_GENERATE(BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF)
 261 #undef BOOST_ASIO_PRIVATE_MAKE_SERVICE_DEF
 262
 263 #endif // defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
 264
 265   /// (Deprecated: Use make_service().) Add a service object to the
 266   /// execution_context.
 267   /**
 268    * This function is used to add a service to the execution_context.
 269    *
 270    * @param e The execution_context object that owns the service.
 271    *
 272    * @param svc The service object. On success, ownership of the service object
 273    * is transferred to the execution_context. When the execution_context object
 274    * is destroyed, it will destroy the service object by performing: @code
 275    * delete static_cast<execution_context::service*>(svc) @endcode
 276    *
 277    * @throws boost::asio::service_already_exists Thrown if a service of the
 278    * given type is already present in the execution_context.
 279    *
 280    * @throws boost::asio::invalid_service_owner Thrown if the service's owning
 281    * execution_context is not the execution_context object specified by the
 282    * @c e parameter.
 283    */
 284   template <typename Service>
 285   friend void add_service(execution_context& e, Service* svc);
 286
 287   /// Determine if an execution_context contains a specified service type.
 288   /**
 289    * This function is used to determine whether the execution_context contains a
 290    * service object corresponding to the given service type.
 291    *
 292    * @param e The execution_context object that owns the service.
 293    *
 294    * @return A boolean indicating whether the execution_context contains the
 295    * service.
 296    */
 297   template <typename Service>
 298   friend bool has_service(execution_context& e);
 299
 300 private:
 301   // The service registry.
 302   boost::asio::detail::service_registry* service_registry_;
 303 };
 304
 305 /// Class used to uniquely identify a service.
 306 class execution_context::id
 307   : private noncopyable
 308 {
 309 public:
 310   /// Constructor.
 311   id() {}
 312 };
 313
 314 /// Base class for all io_context services.
 315 class execution_context::service
 316   : private noncopyable
 317 {
 318 public:
 319   /// Get the context object that owns the service.
 320   execution_context& context();
 321
 322 protected:
 323   /// Constructor.
 324   /**
 325    * @param owner The execution_context object that owns the service.
 326    */
 327   BOOST_ASIO_DECL service(execution_context& owner);
 328
 329   /// Destructor.
 330   BOOST_ASIO_DECL virtual ~service();
 331
 332 private:
 333   /// Destroy all user-defined handler objects owned by the service.
 334   virtual void shutdown() = 0;
 335
 336   /// Handle notification of a fork-related event to perform any necessary
 337   /// housekeeping.
 338   /**
 339    * This function is not a pure virtual so that services only have to
 340    * implement it if necessary. The default implementation does nothing.
 341    */
 342   BOOST_ASIO_DECL virtual void notify_fork(
 343       execution_context::fork_event event);
 344
 345   friend class boost::asio::detail::service_registry;
 346   struct key
 347   {
 348     key() : type_info_(0), id_(0) {}
 349     const std::type_info* type_info_;
 350     const execution_context::id* id_;
 351   } key_;
 352
 353   execution_context& owner_;
 354   service* next_;
 355 };
 356
 357 /// Exception thrown when trying to add a duplicate service to an
 358 /// execution_context.
 359 class service_already_exists
 360   : public std::logic_error
 361 {
 362 public:
 363   BOOST_ASIO_DECL service_already_exists();
 364 };
 365
 366 /// Exception thrown when trying to add a service object to an
 367 /// execution_context where the service has a different owner.
 368 class invalid_service_owner
 369   : public std::logic_error
 370 {
 371 public:
 372   BOOST_ASIO_DECL invalid_service_owner();
 373 };
 374
 375 namespace detail {
 376
 377 // Special derived service id type to keep classes header-file only.
 378 template <typename Type>
 379 class service_id
 380   : public execution_context::id
 381 {
 382 };
 383
 384 // Special service base class to keep classes header-file only.
 385 template <typename Type>
 386 class execution_context_service_base
 387   : public execution_context::service
 388 {
 389 public:
 390   static service_id<Type> id;
 391
 392   // Constructor.
 393   execution_context_service_base(execution_context& e)
 394     : execution_context::service(e)
 395   {
 396   }
 397 };
 398
 399 template <typename Type>
 400 service_id<Type> execution_context_service_base<Type>::id;
 401
 402 } // namespace detail
 403 } // namespace asio
 404 } // namespace boost
 405
 406 #include <boost/asio/detail/pop_options.hpp>
 407
 408 #include <boost/asio/impl/execution_context.hpp>
 409 #if defined(BOOST_ASIO_HEADER_ONLY)
 410 # include <boost/asio/impl/execution_context.ipp>
 411 #endif // defined(BOOST_ASIO_HEADER_ONLY)
 412
 413 #endif // BOOST_ASIO_EXECUTION_CONTEXT_HPP