Statistics
| Revision:

root / tmp / org.txm.statsengine.r.core.win32 / res / win32 / library / BH / include / boost / asio / strand.hpp @ 2486

History | View | Annotate | Download (8.7 kB)

1 2486 sjacqu01
//
2 2486 sjacqu01
// strand.hpp
3 2486 sjacqu01
// ~~~~~~~~~~
4 2486 sjacqu01
//
5 2486 sjacqu01
// Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6 2486 sjacqu01
//
7 2486 sjacqu01
// Distributed under the Boost Software License, Version 1.0. (See accompanying
8 2486 sjacqu01
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 2486 sjacqu01
//
10 2486 sjacqu01
11 2486 sjacqu01
#ifndef BOOST_ASIO_STRAND_HPP
12 2486 sjacqu01
#define BOOST_ASIO_STRAND_HPP
13 2486 sjacqu01
14 2486 sjacqu01
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15 2486 sjacqu01
# pragma once
16 2486 sjacqu01
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17 2486 sjacqu01
18 2486 sjacqu01
#include <boost/asio/detail/config.hpp>
19 2486 sjacqu01
#include <boost/asio/async_result.hpp>
20 2486 sjacqu01
#include <boost/asio/detail/handler_type_requirements.hpp>
21 2486 sjacqu01
#include <boost/asio/detail/strand_service.hpp>
22 2486 sjacqu01
#include <boost/asio/detail/wrapped_handler.hpp>
23 2486 sjacqu01
#include <boost/asio/io_service.hpp>
24 2486 sjacqu01
25 2486 sjacqu01
#include <boost/asio/detail/push_options.hpp>
26 2486 sjacqu01
27 2486 sjacqu01
namespace boost {
28 2486 sjacqu01
namespace asio {
29 2486 sjacqu01
30 2486 sjacqu01
/// Provides serialised handler execution.
31 2486 sjacqu01
/**
32 2486 sjacqu01
 * The io_service::strand class provides the ability to post and dispatch
33 2486 sjacqu01
 * handlers with the guarantee that none of those handlers will execute
34 2486 sjacqu01
 * concurrently.
35 2486 sjacqu01
 *
36 2486 sjacqu01
 * @par Order of handler invocation
37 2486 sjacqu01
 * Given:
38 2486 sjacqu01
 *
39 2486 sjacqu01
 * @li a strand object @c s
40 2486 sjacqu01
 *
41 2486 sjacqu01
 * @li an object @c a meeting completion handler requirements
42 2486 sjacqu01
 *
43 2486 sjacqu01
 * @li an object @c a1 which is an arbitrary copy of @c a made by the
44 2486 sjacqu01
 * implementation
45 2486 sjacqu01
 *
46 2486 sjacqu01
 * @li an object @c b meeting completion handler requirements
47 2486 sjacqu01
 *
48 2486 sjacqu01
 * @li an object @c b1 which is an arbitrary copy of @c b made by the
49 2486 sjacqu01
 * implementation
50 2486 sjacqu01
 *
51 2486 sjacqu01
 * if any of the following conditions are true:
52 2486 sjacqu01
 *
53 2486 sjacqu01
 * @li @c s.post(a) happens-before @c s.post(b)
54 2486 sjacqu01
 *
55 2486 sjacqu01
 * @li @c s.post(a) happens-before @c s.dispatch(b), where the latter is
56 2486 sjacqu01
 * performed outside the strand
57 2486 sjacqu01
 *
58 2486 sjacqu01
 * @li @c s.dispatch(a) happens-before @c s.post(b), where the former is
59 2486 sjacqu01
 * performed outside the strand
60 2486 sjacqu01
 *
61 2486 sjacqu01
 * @li @c s.dispatch(a) happens-before @c s.dispatch(b), where both are
62 2486 sjacqu01
 * performed outside the strand
63 2486 sjacqu01
 *
64 2486 sjacqu01
 * then @c asio_handler_invoke(a1, &a1) happens-before
65 2486 sjacqu01
 * @c asio_handler_invoke(b1, &b1).
66 2486 sjacqu01
 *
67 2486 sjacqu01
 * Note that in the following case:
68 2486 sjacqu01
 * @code async_op_1(..., s.wrap(a));
69 2486 sjacqu01
 * async_op_2(..., s.wrap(b)); @endcode
70 2486 sjacqu01
 * the completion of the first async operation will perform @c s.dispatch(a),
71 2486 sjacqu01
 * and the second will perform @c s.dispatch(b), but the order in which those
72 2486 sjacqu01
 * are performed is unspecified. That is, you cannot state whether one
73 2486 sjacqu01
 * happens-before the other. Therefore none of the above conditions are met and
74 2486 sjacqu01
 * no ordering guarantee is made.
75 2486 sjacqu01
 *
76 2486 sjacqu01
 * @note The implementation makes no guarantee that handlers posted or
77 2486 sjacqu01
 * dispatched through different @c strand objects will be invoked concurrently.
78 2486 sjacqu01
 *
79 2486 sjacqu01
 * @par Thread Safety
80 2486 sjacqu01
 * @e Distinct @e objects: Safe.@n
81 2486 sjacqu01
 * @e Shared @e objects: Safe.
82 2486 sjacqu01
 *
83 2486 sjacqu01
 * @par Concepts:
84 2486 sjacqu01
 * Dispatcher.
85 2486 sjacqu01
 */
86 2486 sjacqu01
class io_service::strand
87 2486 sjacqu01
{
88 2486 sjacqu01
public:
89 2486 sjacqu01
  /// Constructor.
90 2486 sjacqu01
  /**
91 2486 sjacqu01
   * Constructs the strand.
92 2486 sjacqu01
   *
93 2486 sjacqu01
   * @param io_service The io_service object that the strand will use to
94 2486 sjacqu01
   * dispatch handlers that are ready to be run.
95 2486 sjacqu01
   */
96 2486 sjacqu01
  explicit strand(boost::asio::io_service& io_service)
97 2486 sjacqu01
    : service_(boost::asio::use_service<
98 2486 sjacqu01
        boost::asio::detail::strand_service>(io_service))
99 2486 sjacqu01
  {
100 2486 sjacqu01
    service_.construct(impl_);
101 2486 sjacqu01
  }
102 2486 sjacqu01
103 2486 sjacqu01
  /// Destructor.
104 2486 sjacqu01
  /**
105 2486 sjacqu01
   * Destroys a strand.
106 2486 sjacqu01
   *
107 2486 sjacqu01
   * Handlers posted through the strand that have not yet been invoked will
108 2486 sjacqu01
   * still be dispatched in a way that meets the guarantee of non-concurrency.
109 2486 sjacqu01
   */
110 2486 sjacqu01
  ~strand()
111 2486 sjacqu01
  {
112 2486 sjacqu01
  }
113 2486 sjacqu01
114 2486 sjacqu01
  /// Get the io_service associated with the strand.
115 2486 sjacqu01
  /**
116 2486 sjacqu01
   * This function may be used to obtain the io_service object that the strand
117 2486 sjacqu01
   * uses to dispatch handlers for asynchronous operations.
118 2486 sjacqu01
   *
119 2486 sjacqu01
   * @return A reference to the io_service object that the strand will use to
120 2486 sjacqu01
   * dispatch handlers. Ownership is not transferred to the caller.
121 2486 sjacqu01
   */
122 2486 sjacqu01
  boost::asio::io_service& get_io_service()
123 2486 sjacqu01
  {
124 2486 sjacqu01
    return service_.get_io_service();
125 2486 sjacqu01
  }
126 2486 sjacqu01
127 2486 sjacqu01
  /// Request the strand to invoke the given handler.
128 2486 sjacqu01
  /**
129 2486 sjacqu01
   * This function is used to ask the strand to execute the given handler.
130 2486 sjacqu01
   *
131 2486 sjacqu01
   * The strand object guarantees that handlers posted or dispatched through
132 2486 sjacqu01
   * the strand will not be executed concurrently. The handler may be executed
133 2486 sjacqu01
   * inside this function if the guarantee can be met. If this function is
134 2486 sjacqu01
   * called from within a handler that was posted or dispatched through the same
135 2486 sjacqu01
   * strand, then the new handler will be executed immediately.
136 2486 sjacqu01
   *
137 2486 sjacqu01
   * The strand's guarantee is in addition to the guarantee provided by the
138 2486 sjacqu01
   * underlying io_service. The io_service guarantees that the handler will only
139 2486 sjacqu01
   * be called in a thread in which the io_service's run member function is
140 2486 sjacqu01
   * currently being invoked.
141 2486 sjacqu01
   *
142 2486 sjacqu01
   * @param handler The handler to be called. The strand will make a copy of the
143 2486 sjacqu01
   * handler object as required. The function signature of the handler must be:
144 2486 sjacqu01
   * @code void handler(); @endcode
145 2486 sjacqu01
   */
146 2486 sjacqu01
  template <typename CompletionHandler>
147 2486 sjacqu01
  BOOST_ASIO_INITFN_RESULT_TYPE(CompletionHandler, void ())
148 2486 sjacqu01
  dispatch(BOOST_ASIO_MOVE_ARG(CompletionHandler) handler)
149 2486 sjacqu01
  {
150 2486 sjacqu01
    // If you get an error on the following line it means that your handler does
151 2486 sjacqu01
    // not meet the documented type requirements for a CompletionHandler.
152 2486 sjacqu01
    BOOST_ASIO_COMPLETION_HANDLER_CHECK(CompletionHandler, handler) type_check;
153 2486 sjacqu01
154 2486 sjacqu01
    detail::async_result_init<
155 2486 sjacqu01
      CompletionHandler, void ()> init(
156 2486 sjacqu01
        BOOST_ASIO_MOVE_CAST(CompletionHandler)(handler));
157 2486 sjacqu01
158 2486 sjacqu01
    service_.dispatch(impl_, init.handler);
159 2486 sjacqu01
160 2486 sjacqu01
    return init.result.get();
161 2486 sjacqu01
  }
162 2486 sjacqu01
163 2486 sjacqu01
  /// Request the strand to invoke the given handler and return
164 2486 sjacqu01
  /// immediately.
165 2486 sjacqu01
  /**
166 2486 sjacqu01
   * This function is used to ask the strand to execute the given handler, but
167 2486 sjacqu01
   * without allowing the strand to call the handler from inside this function.
168 2486 sjacqu01
   *
169 2486 sjacqu01
   * The strand object guarantees that handlers posted or dispatched through
170 2486 sjacqu01
   * the strand will not be executed concurrently. The strand's guarantee is in
171 2486 sjacqu01
   * addition to the guarantee provided by the underlying io_service. The
172 2486 sjacqu01
   * io_service guarantees that the handler will only be called in a thread in
173 2486 sjacqu01
   * which the io_service's run member function is currently being invoked.
174 2486 sjacqu01
   *
175 2486 sjacqu01
   * @param handler The handler to be called. The strand will make a copy of the
176 2486 sjacqu01
   * handler object as required. The function signature of the handler must be:
177 2486 sjacqu01
   * @code void handler(); @endcode
178 2486 sjacqu01
   */
179 2486 sjacqu01
  template <typename CompletionHandler>
180 2486 sjacqu01
  BOOST_ASIO_INITFN_RESULT_TYPE(CompletionHandler, void ())
181 2486 sjacqu01
  post(BOOST_ASIO_MOVE_ARG(CompletionHandler) handler)
182 2486 sjacqu01
  {
183 2486 sjacqu01
    // If you get an error on the following line it means that your handler does
184 2486 sjacqu01
    // not meet the documented type requirements for a CompletionHandler.
185 2486 sjacqu01
    BOOST_ASIO_COMPLETION_HANDLER_CHECK(CompletionHandler, handler) type_check;
186 2486 sjacqu01
187 2486 sjacqu01
    detail::async_result_init<
188 2486 sjacqu01
      CompletionHandler, void ()> init(
189 2486 sjacqu01
        BOOST_ASIO_MOVE_CAST(CompletionHandler)(handler));
190 2486 sjacqu01
191 2486 sjacqu01
    service_.post(impl_, init.handler);
192 2486 sjacqu01
193 2486 sjacqu01
    return init.result.get();
194 2486 sjacqu01
  }
195 2486 sjacqu01
196 2486 sjacqu01
  /// Create a new handler that automatically dispatches the wrapped handler
197 2486 sjacqu01
  /// on the strand.
198 2486 sjacqu01
  /**
199 2486 sjacqu01
   * This function is used to create a new handler function object that, when
200 2486 sjacqu01
   * invoked, will automatically pass the wrapped handler to the strand's
201 2486 sjacqu01
   * dispatch function.
202 2486 sjacqu01
   *
203 2486 sjacqu01
   * @param handler The handler to be wrapped. The strand will make a copy of
204 2486 sjacqu01
   * the handler object as required. The function signature of the handler must
205 2486 sjacqu01
   * be: @code void handler(A1 a1, ... An an); @endcode
206 2486 sjacqu01
   *
207 2486 sjacqu01
   * @return A function object that, when invoked, passes the wrapped handler to
208 2486 sjacqu01
   * the strand's dispatch function. Given a function object with the signature:
209 2486 sjacqu01
   * @code R f(A1 a1, ... An an); @endcode
210 2486 sjacqu01
   * If this function object is passed to the wrap function like so:
211 2486 sjacqu01
   * @code strand.wrap(f); @endcode
212 2486 sjacqu01
   * then the return value is a function object with the signature
213 2486 sjacqu01
   * @code void g(A1 a1, ... An an); @endcode
214 2486 sjacqu01
   * that, when invoked, executes code equivalent to:
215 2486 sjacqu01
   * @code strand.dispatch(boost::bind(f, a1, ... an)); @endcode
216 2486 sjacqu01
   */
217 2486 sjacqu01
  template <typename Handler>
218 2486 sjacqu01
#if defined(GENERATING_DOCUMENTATION)
219 2486 sjacqu01
  unspecified
220 2486 sjacqu01
#else
221 2486 sjacqu01
  detail::wrapped_handler<strand, Handler, detail::is_continuation_if_running>
222 2486 sjacqu01
#endif
223 2486 sjacqu01
  wrap(Handler handler)
224 2486 sjacqu01
  {
225 2486 sjacqu01
    return detail::wrapped_handler<io_service::strand, Handler,
226 2486 sjacqu01
        detail::is_continuation_if_running>(*this, handler);
227 2486 sjacqu01
  }
228 2486 sjacqu01
229 2486 sjacqu01
  /// Determine whether the strand is running in the current thread.
230 2486 sjacqu01
  /**
231 2486 sjacqu01
   * @return @c true if the current thread is executing a handler that was
232 2486 sjacqu01
   * submitted to the strand using post(), dispatch() or wrap(). Otherwise
233 2486 sjacqu01
   * returns @c false.
234 2486 sjacqu01
   */
235 2486 sjacqu01
  bool running_in_this_thread() const
236 2486 sjacqu01
  {
237 2486 sjacqu01
    return service_.running_in_this_thread(impl_);
238 2486 sjacqu01
  }
239 2486 sjacqu01
240 2486 sjacqu01
private:
241 2486 sjacqu01
  boost::asio::detail::strand_service& service_;
242 2486 sjacqu01
  boost::asio::detail::strand_service::implementation_type impl_;
243 2486 sjacqu01
};
244 2486 sjacqu01
245 2486 sjacqu01
/// (Deprecated: Use boost::asio::io_service::strand.) Typedef for backwards
246 2486 sjacqu01
/// compatibility.
247 2486 sjacqu01
typedef boost::asio::io_service::strand strand;
248 2486 sjacqu01
249 2486 sjacqu01
} // namespace asio
250 2486 sjacqu01
} // namespace boost
251 2486 sjacqu01
252 2486 sjacqu01
#include <boost/asio/detail/pop_options.hpp>
253 2486 sjacqu01
254 2486 sjacqu01
#endif // BOOST_ASIO_STRAND_HPP