boost/asio/handler_invoke_hook.hpp

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