boost/asio/compose.hpp

0001 //
0002 // compose.hpp
0003 // ~~~~~~~~~~~
0004 //
0005 // Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009 //
0010
0011 #ifndef BOOST_ASIO_COMPOSE_HPP
0012 #define BOOST_ASIO_COMPOSE_HPP
0013
0014 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
0015 # pragma once
0016 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
0017
0018 #include <boost/asio/detail/config.hpp>
0019 #include <boost/asio/composed.hpp>
0020
0021 #include <boost/asio/detail/push_options.hpp>
0022
0023 namespace boost {
0024 namespace asio {
0025
0026 /// Launch an asynchronous operation with a stateful implementation.
0027 /**
0028  * The async_compose function simplifies the implementation of composed
0029  * asynchronous operations automatically wrapping a stateful function object
0030  * with a conforming intermediate completion handler.
0031  *
0032  * @param implementation A function object that contains the implementation of
0033  * the composed asynchronous operation. The first argument to the function
0034  * object is a non-const reference to the enclosing intermediate completion
0035  * handler. The remaining arguments are any arguments that originate from the
0036  * completion handlers of any asynchronous operations performed by the
0037  * implementation.
0038  *
0039  * @param token The completion token.
0040  *
0041  * @param io_objects_or_executors Zero or more I/O objects or I/O executors for
0042  * which outstanding work must be maintained.
0043  *
0044  * @par Per-Operation Cancellation
0045  * By default, terminal per-operation cancellation is enabled for
0046  * composed operations that are implemented using @c async_compose. To
0047  * disable cancellation for the composed operation, or to alter its
0048  * supported cancellation types, call the @c self object's @c
0049  * reset_cancellation_state function.
0050  *
0051  * @par Example:
0052  *
0053  * @code struct async_echo_implementation
0054  * {
0055  *   tcp::socket& socket_;
0056  *   boost::asio::mutable_buffer buffer_;
0057  *   enum { starting, reading, writing } state_;
0058  *
0059  *   template <typename Self>
0060  *   void operator()(Self& self,
0061  *       boost::system::error_code error = {},
0062  *       std::size_t n = 0)
0063  *   {
0064  *     switch (state_)
0065  *     {
0066  *     case starting:
0067  *       state_ = reading;
0068  *       socket_.async_read_some(
0069  *           buffer_, std::move(self));
0070  *       break;
0071  *     case reading:
0072  *       if (error)
0073  *       {
0074  *         self.complete(error, 0);
0075  *       }
0076  *       else
0077  *       {
0078  *         state_ = writing;
0079  *         boost::asio::async_write(socket_, buffer_,
0080  *             boost::asio::transfer_exactly(n),
0081  *             std::move(self));
0082  *       }
0083  *       break;
0084  *     case writing:
0085  *       self.complete(error, n);
0086  *       break;
0087  *     }
0088  *   }
0089  * };
0090  *
0091  * template <typename CompletionToken>
0092  * auto async_echo(tcp::socket& socket,
0093  *     boost::asio::mutable_buffer buffer,
0094  *     CompletionToken&& token)
0095  *   -> decltype(
0096  *     boost::asio::async_compose<CompletionToken,
0097  *       void(boost::system::error_code, std::size_t)>(
0098  *         std::declval<async_echo_implementation>(),
0099  *         token, socket))
0100  * {
0101  *   return boost::asio::async_compose<CompletionToken,
0102  *     void(boost::system::error_code, std::size_t)>(
0103  *       async_echo_implementation{socket, buffer,
0104  *         async_echo_implementation::starting},
0105  *       token, socket);
0106  * } @endcode
0107  */
0108 template <typename CompletionToken, typename Signature,
0109     typename Implementation, typename... IoObjectsOrExecutors>
0110 inline auto async_compose(Implementation&& implementation,
0111     type_identity_t<CompletionToken>& token,
0112     IoObjectsOrExecutors&&... io_objects_or_executors)
0113   -> decltype(
0114     async_initiate<CompletionToken, Signature>(
0115       composed<Signature>(static_cast<Implementation&&>(implementation),
0116         static_cast<IoObjectsOrExecutors&&>(io_objects_or_executors)...),
0117       token))
0118 {
0119   return async_initiate<CompletionToken, Signature>(
0120       composed<Signature>(static_cast<Implementation&&>(implementation),
0121         static_cast<IoObjectsOrExecutors&&>(io_objects_or_executors)...),
0122       token);
0123 }
0124
0125 } // namespace asio
0126 } // namespace boost
0127
0128 #include <boost/asio/detail/pop_options.hpp>
0129
0130 #endif // BOOST_ASIO_COMPOSE_HPP