boost/asio/strand.hpp

   1 //
   2 // strand.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_STRAND_HPP
  12 #define BOOST_ASIO_STRAND_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 #include <boost/asio/io_service.hpp>
  21 #include <boost/asio/detail/strand_service.hpp>
  22 #include <boost/asio/detail/wrapped_handler.hpp>
  23
  24 namespace boost {
  25 namespace asio {
  26
  27 /// Provides serialised handler execution.
  28 /**
  29  * The io_service::strand class provides the ability to post and dispatch
  30  * handlers with the guarantee that none of those handlers will execute
  31  * concurrently.
  32  *
  33  * @par Thread Safety
  34  * @e Distinct @e objects: Safe.@n
  35  * @e Shared @e objects: Safe.
  36  *
  37  * @par Concepts:
  38  * Dispatcher.
  39  */
  40 class io_service::strand
  41 {
  42 public:
  43   /// Constructor.
  44   /**
  45    * Constructs the strand.
  46    *
  47    * @param io_service The io_service object that the strand will use to
  48    * dispatch handlers that are ready to be run.
  49    */
  50   explicit strand(boost::asio::io_service& io_service)
  51     : service_(boost::asio::use_service<
  52         boost::asio::detail::strand_service>(io_service))
  53   {
  54     service_.construct(impl_);
  55   }
  56
  57   /// Destructor.
  58   /**
  59    * Destroys a strand.
  60    *
  61    * Handlers posted through the strand that have not yet been invoked will
  62    * still be dispatched in a way that meets the guarantee of non-concurrency.
  63    */
  64   ~strand()
  65   {
  66     service_.destroy(impl_);
  67   }
  68
  69   /// (Deprecated: use get_io_service().) Get the io_service associated with
  70   /// the strand.
  71   /**
  72    * This function may be used to obtain the io_service object that the strand
  73    * uses to dispatch handlers for asynchronous operations.
  74    *
  75    * @return A reference to the io_service object that the strand will use to
  76    * dispatch handlers. Ownership is not transferred to the caller.
  77    */
  78   boost::asio::io_service& io_service()
  79   {
  80     return service_.get_io_service();
  81   }
  82
  83   /// Get the io_service associated with the strand.
  84   /**
  85    * This function may be used to obtain the io_service object that the strand
  86    * uses to dispatch handlers for asynchronous operations.
  87    *
  88    * @return A reference to the io_service object that the strand will use to
  89    * dispatch handlers. Ownership is not transferred to the caller.
  90    */
  91   boost::asio::io_service& get_io_service()
  92   {
  93     return service_.get_io_service();
  94   }
  95
  96   /// Request the strand to invoke the given handler.
  97   /**
  98    * This function is used to ask the strand to execute the given handler.
  99    *
 100    * The strand object guarantees that handlers posted or dispatched through
 101    * the strand will not be executed concurrently. The handler may be executed
 102    * inside this function if the guarantee can be met. If this function is
 103    * called from within a handler that was posted or dispatched through the same
 104    * strand, then the new handler will be executed immediately.
 105    *
 106    * The strand's guarantee is in addition to the guarantee provided by the
 107    * underlying io_service. The io_service guarantees that the handler will only
 108    * be called in a thread in which the io_service's run member function is
 109    * currently being invoked.
 110    *
 111    * @param handler The handler to be called. The strand will make a copy of the
 112    * handler object as required. The function signature of the handler must be:
 113    * @code void handler(); @endcode
 114    */
 115   template <typename Handler>
 116   void dispatch(Handler handler)
 117   {
 118     service_.dispatch(impl_, handler);
 119   }
 120
 121   /// Request the strand to invoke the given handler and return
 122   /// immediately.
 123   /**
 124    * This function is used to ask the strand to execute the given handler, but
 125    * without allowing the strand to call the handler from inside this function.
 126    *
 127    * The strand object guarantees that handlers posted or dispatched through
 128    * the strand will not be executed concurrently. The strand's guarantee is in
 129    * addition to the guarantee provided by the underlying io_service. The
 130    * io_service guarantees that the handler will only be called in a thread in
 131    * which the io_service's run member function is currently being invoked.
 132    *
 133    * @param handler The handler to be called. The strand will make a copy of the
 134    * handler object as required. The function signature of the handler must be:
 135    * @code void handler(); @endcode
 136    */
 137   template <typename Handler>
 138   void post(Handler handler)
 139   {
 140     service_.post(impl_, handler);
 141   }
 142
 143   /// Create a new handler that automatically dispatches the wrapped handler
 144   /// on the strand.
 145   /**
 146    * This function is used to create a new handler function object that, when
 147    * invoked, will automatically pass the wrapped handler to the strand's
 148    * dispatch function.
 149    *
 150    * @param handler The handler to be wrapped. The strand will make a copy of
 151    * the handler object as required. The function signature of the handler must
 152    * be: @code void handler(A1 a1, ... An an); @endcode
 153    *
 154    * @return A function object that, when invoked, passes the wrapped handler to
 155    * the strand's dispatch function. Given a function object with the signature:
 156    * @code R f(A1 a1, ... An an); @endcode
 157    * If this function object is passed to the wrap function like so:
 158    * @code strand.wrap(f); @endcode
 159    * then the return value is a function object with the signature
 160    * @code void g(A1 a1, ... An an); @endcode
 161    * that, when invoked, executes code equivalent to:
 162    * @code strand.dispatch(boost::bind(f, a1, ... an)); @endcode
 163    */
 164   template <typename Handler>
 165 #if defined(GENERATING_DOCUMENTATION)
 166   unspecified
 167 #else
 168   detail::wrapped_handler<strand, Handler>
 169 #endif
 170   wrap(Handler handler)
 171   {
 172     return detail::wrapped_handler<io_service::strand, Handler>(*this, handler);
 173   }
 174
 175 private:
 176   boost::asio::detail::strand_service& service_;
 177   boost::asio::detail::strand_service::implementation_type impl_;
 178 };
 179
 180 /// Typedef for backwards compatibility.
 181 typedef boost::asio::io_service::strand strand;
 182
 183 } // namespace asio
 184 } // namespace boost
 185
 186 #include <boost/asio/detail/pop_options.hpp>
 187
 188 #endif // BOOST_ASIO_STRAND_HPP