boost/asio/handler_invoke_hook.hpp

   1 //
   2 // handler_invoke_hook.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2014 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_HANDLER_INVOKE_HOOK_HPP
  12 #define BOOST_ASIO_HANDLER_INVOKE_HOOK_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
  20 #include <boost/asio/detail/push_options.hpp>
  21
  22 namespace boost {
  23 namespace asio {
  24
  25 /** @defgroup asio_handler_invoke boost::asio::asio_handler_invoke
  26  *
  27  * @brief Default invoke function for handlers.
  28  *
  29  * Completion handlers for asynchronous operations are invoked by the
  30  * io_service associated with the corresponding object (e.g. a socket or
  31  * deadline_timer). Certain guarantees are made on when the handler may be
  32  * invoked, in particular that a handler can only be invoked from a thread that
  33  * is currently calling @c run() on the corresponding io_service object.
  34  * Handlers may subsequently be invoked through other objects (such as
  35  * io_service::strand objects) that provide additional guarantees.
  36  *
  37  * When asynchronous operations are composed from other asynchronous
  38  * operations, all intermediate handlers should be invoked using the same
  39  * method as the final handler. This is required to ensure that user-defined
  40  * objects are not accessed in a way that may violate the guarantees. This
  41  * hooking function ensures that the invoked method used for the final handler
  42  * is accessible at each intermediate step.
  43  *
  44  * Implement asio_handler_invoke for your own handlers to specify a custom
  45  * invocation strategy.
  46  *
  47  * This default implementation invokes the function object like so:
  48  * @code function(); @endcode
  49  * If necessary, the default implementation makes a copy of the function object
  50  * so that the non-const operator() can be used.
  51  *
  52  * @par Example
  53  * @code
  54  * class my_handler;
  55  *
  56  * template <typename Function>
  57  * void asio_handler_invoke(Function function, my_handler* context)
  58  * {
  59  *   context->strand_.dispatch(function);
  60  * }
  61  * @endcode
  62  */
  63 /*@{*/
  64
  65 /// Default handler invocation hook used for non-const function objects.
  66 template <typename Function>
  67 inline void asio_handler_invoke(Function& function, ...)
  68 {
  69   function();
  70 }
  71
  72 /// Default handler invocation hook used for const function objects.
  73 template <typename Function>
  74 inline void asio_handler_invoke(const Function& function, ...)
  75 {
  76   Function tmp(function);
  77   tmp();
  78 }
  79
  80 /*@}*/
  81
  82 } // namespace asio
  83 } // namespace boost
  84
  85 #include <boost/asio/detail/pop_options.hpp>
  86
  87 #endif // BOOST_ASIO_HANDLER_INVOKE_HOOK_HPP