1 //
2 // handler_invoke_hook.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~~~
4 //
5 // Copyright (c) 2003-2021 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 (Deprecated: Use the associated_executor trait.) Default invoke
28 * function for handlers.
29 *
30 * Completion handlers for asynchronous operations are invoked by the
31 * io_context associated with the corresponding object (e.g. a socket or
32 * deadline_timer). Certain guarantees are made on when the handler may be
33 * invoked, in particular that a handler can only be invoked from a thread that
34 * is currently calling @c run() on the corresponding io_context object.
35 * Handlers may subsequently be invoked through other objects (such as
36 * io_context::strand objects) that provide additional guarantees.
37 *
38 * When asynchronous operations are composed from other asynchronous
39 * operations, all intermediate handlers should be invoked using the same
40 * method as the final handler. This is required to ensure that user-defined
41 * objects are not accessed in a way that may violate the guarantees. This
42 * hooking function ensures that the invoked method used for the final handler
43 * is accessible at each intermediate step.
44 *
45 * Implement asio_handler_invoke for your own handlers to specify a custom
46 * invocation strategy.
47 *
48 * This default implementation invokes the function object like so:
49 * @code function(); @endcode
50 * If necessary, the default implementation makes a copy of the function object
51 * so that the non-const operator() can be used.
52 *
53 * @par Example
54 * @code
55 * class my_handler;
56 *
57 * template <typename Function>
58 * void asio_handler_invoke(Function function, my_handler* context)
59 * {
60 * context->strand_.dispatch(function);
61 * }
62 * @endcode
63 */
64 /*@{*/
65
66 #if defined(BOOST_ASIO_NO_DEPRECATED)
67
68 // Places in asio that would have previously called the invocation hook to
69 // execute a handler, now call it only to check whether the result type is this
70 // type. If the result is not this type, it indicates that the user code still
71 // has the old hooks in place, and if so we want to trigger a compile error.
72 enum asio_handler_invoke_is_no_longer_used {};
73
74 typedef asio_handler_invoke_is_no_longer_used
75 asio_handler_invoke_is_deprecated;
76
77 #else // defined(BOOST_ASIO_NO_DEPRECATED)
78
79 typedef void asio_handler_invoke_is_deprecated;
80
81 #endif // defined(BOOST_ASIO_NO_DEPRECATED)
82
83 /// Default handler invocation hook used for non-const function objects.
84 template <typename Function>
85 inline asio_handler_invoke_is_deprecated
asio_handler_invoke(Function & function,...)86 asio_handler_invoke(Function& function, ...)
87 {
88 function();
89 #if defined(BOOST_ASIO_NO_DEPRECATED)
90 return asio_handler_invoke_is_no_longer_used();
91 #endif // defined(BOOST_ASIO_NO_DEPRECATED)
92 }
93
94 /// Default handler invocation hook used for const function objects.
95 template <typename Function>
96 inline asio_handler_invoke_is_deprecated
asio_handler_invoke(const Function & function,...)97 asio_handler_invoke(const Function& function, ...)
98 {
99 Function tmp(function);
100 tmp();
101 #if defined(BOOST_ASIO_NO_DEPRECATED)
102 return asio_handler_invoke_is_no_longer_used();
103 #endif // defined(BOOST_ASIO_NO_DEPRECATED)
104 }
105
106 /*@}*/
107
108 } // namespace asio
109 } // namespace boost
110
111 #include <boost/asio/detail/pop_options.hpp>
112
113 #endif // BOOST_ASIO_HANDLER_INVOKE_HOOK_HPP
114