dispatch.hpp
7.38 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
//
// dispatch.hpp
// ~~~~~~~~~~~~
//
// Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
#ifndef BOOST_ASIO_DISPATCH_HPP
#define BOOST_ASIO_DISPATCH_HPP
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
# pragma once
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
#include <boost/asio/detail/config.hpp>
#include <boost/asio/async_result.hpp>
#include <boost/asio/detail/type_traits.hpp>
#include <boost/asio/execution_context.hpp>
#include <boost/asio/execution/executor.hpp>
#include <boost/asio/is_executor.hpp>
#include <boost/asio/detail/push_options.hpp>
namespace boost {
namespace asio {
namespace detail {
class initiate_dispatch;
template <typename> class initiate_dispatch_with_executor;
} // namespace detail
/// Submits a completion token or function object for execution.
/**
* This function submits an object for execution using the object's associated
* executor. The function object may be called from the current thread prior to
* returning from <tt>dispatch()</tt>. Otherwise, it is queued for execution.
*
* @param token The @ref completion_token that will be used to produce a
* completion handler. The function signature of the completion handler must be:
* @code void handler(); @endcode
*
* @returns This function returns <tt>async_initiate<NullaryToken,
* void()>(Init{}, token)</tt>, where @c Init is a function object type defined
* as:
*
* @code class Init
* {
* public:
* template <typename CompletionHandler>
* void operator()(CompletionHandler&& completion_handler) const;
* }; @endcode
*
* The function call operator of @c Init:
*
* @li Obtains the handler's associated executor object @c ex of type @c Ex by
* performing @code auto ex = get_associated_executor(handler); @endcode
*
* @li Obtains the handler's associated allocator object @c alloc by performing
* @code auto alloc = get_associated_allocator(handler); @endcode
*
* @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs
* @code prefer(ex, execution::allocator(alloc)).execute(
* std::forward<CompletionHandler>(completion_handler)); @endcode
*
* @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs
* @code ex.dispatch(
* std::forward<CompletionHandler>(completion_handler),
* alloc); @endcode
*
* @par Completion Signature
* @code void() @endcode
*/
template <BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken>
BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_PREFIX(NullaryToken, void()) dispatch(
BOOST_ASIO_MOVE_ARG(NullaryToken) token)
BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_SUFFIX((
async_initiate<NullaryToken, void()>(
declval<detail::initiate_dispatch>(), token)));
/// Submits a completion token or function object for execution.
/**
* This function submits an object for execution using the specified executor.
* The function object may be called from the current thread prior to returning
* from <tt>dispatch()</tt>. Otherwise, it is queued for execution.
*
* @param ex The target executor.
*
* @param token The @ref completion_token that will be used to produce a
* completion handler. The function signature of the completion handler must be:
* @code void handler(); @endcode
*
* @returns This function returns <tt>async_initiate<NullaryToken,
* void()>(Init{ex}, token)</tt>, where @c Init is a function object type
* defined as:
*
* @code class Init
* {
* public:
* using executor_type = Executor;
* explicit Init(const Executor& ex) : ex_(ex) {}
* executor_type get_executor() const noexcept { return ex_; }
* template <typename CompletionHandler>
* void operator()(CompletionHandler&& completion_handler) const;
* private:
* Executor ex_; // exposition only
* }; @endcode
*
* The function call operator of @c Init:
*
* @li Obtains the handler's associated executor object @c ex1 of type @c Ex1 by
* performing @code auto ex1 = get_associated_executor(handler, ex); @endcode
*
* @li Obtains the handler's associated allocator object @c alloc by performing
* @code auto alloc = get_associated_allocator(handler); @endcode
*
* @li If <tt>execution::is_executor<Ex1>::value</tt> is true, constructs a
* function object @c f with a member @c executor_ that is initialised with
* <tt>prefer(ex1, execution::outstanding_work.tracked)</tt>, a member @c
* handler_ that is a decay-copy of @c completion_handler, and a function call
* operator that performs:
* @code auto a = get_associated_allocator(handler_);
* prefer(executor_, execution::allocator(a)).execute(std::move(handler_));
* @endcode
*
* @li If <tt>execution::is_executor<Ex1>::value</tt> is false, constructs a
* function object @c f with a member @c work_ that is initialised with
* <tt>make_work_guard(ex1)</tt>, a member @c handler_ that is a decay-copy of
* @c completion_handler, and a function call operator that performs:
* @code auto a = get_associated_allocator(handler_);
* work_.get_executor().dispatch(std::move(handler_), a);
* work_.reset(); @endcode
*
* @li If <tt>execution::is_executor<Ex>::value</tt> is true, performs
* @code prefer(ex, execution::allocator(alloc)).execute(std::move(f)); @endcode
*
* @li If <tt>execution::is_executor<Ex>::value</tt> is false, performs
* @code ex.dispatch(std::move(f), alloc); @endcode
*
* @par Completion Signature
* @code void() @endcode
*/
template <typename Executor,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_PREFIX(NullaryToken, void()) dispatch(
const Executor& ex,
BOOST_ASIO_MOVE_ARG(NullaryToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
typename constraint<
execution::is_executor<Executor>::value || is_executor<Executor>::value
>::type = 0)
BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_SUFFIX((
async_initiate<NullaryToken, void()>(
declval<detail::initiate_dispatch_with_executor<Executor> >(), token)));
/// Submits a completion token or function object for execution.
/**
* @param ctx An execution context, from which the target executor is obtained.
*
* @param token The @ref completion_token that will be used to produce a
* completion handler. The function signature of the completion handler must be:
* @code void handler(); @endcode
*
* @returns <tt>dispatch(ctx.get_executor(),
* forward<NullaryToken>(token))</tt>.
*
* @par Completion Signature
* @code void() @endcode
*/
template <typename ExecutionContext,
BOOST_ASIO_COMPLETION_TOKEN_FOR(void()) NullaryToken
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
typename ExecutionContext::executor_type)>
BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_PREFIX(NullaryToken, void()) dispatch(
ExecutionContext& ctx,
BOOST_ASIO_MOVE_ARG(NullaryToken) token
BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
typename ExecutionContext::executor_type),
typename constraint<is_convertible<
ExecutionContext&, execution_context&>::value>::type = 0)
BOOST_ASIO_INITFN_AUTO_RESULT_TYPE_SUFFIX((
async_initiate<NullaryToken, void()>(
declval<detail::initiate_dispatch_with_executor<
typename ExecutionContext::executor_type> >(), token)));
} // namespace asio
} // namespace boost
#include <boost/asio/detail/pop_options.hpp>
#include <boost/asio/impl/dispatch.hpp>
#endif // BOOST_ASIO_DISPATCH_HPP