| 36 | |
| 37 | template <typename T, typename CompletionToken> |
| 38 | auto async_write_message(tcp::socket& socket, |
| 39 | const T& message, CompletionToken&& token) |
| 40 | // The return type of the initiating function is deduced from the combination |
| 41 | // of: |
| 42 | // |
| 43 | // - the CompletionToken type, |
| 44 | // - the completion handler signature, and |
| 45 | // - the asynchronous operation's initiation function object. |
| 46 | // |
| 47 | // When the completion token is a simple callback, the return type is always |
| 48 | // void. In this example, when the completion token is boost::asio::yield_context |
| 49 | // (used for stackful coroutines) the return type would also be void, as |
| 50 | // there is no non-error argument to the completion handler. When the |
| 51 | // completion token is boost::asio::use_future it would be std::future<void>. When |
| 52 | // the completion token is boost::asio::deferred, the return type differs for each |
| 53 | // asynchronous operation. |
| 54 | // |
| 55 | // In C++14 we can omit the return type as it is automatically deduced from |
| 56 | // the return type of boost::asio::async_initiate. |
| 57 | { |
| 58 | // In addition to determining the mechanism by which an asynchronous |
| 59 | // operation delivers its result, a completion token also determines the time |
| 60 | // when the operation commences. For example, when the completion token is a |
| 61 | // simple callback the operation commences before the initiating function |
| 62 | // returns. However, if the completion token's delivery mechanism uses a |
| 63 | // future, we might instead want to defer initiation of the operation until |
| 64 | // the returned future object is waited upon. |
| 65 | // |
| 66 | // To enable this, when implementing an asynchronous operation we must |
| 67 | // package the initiation step as a function object. The initiation function |
| 68 | // object's call operator is passed the concrete completion handler produced |
| 69 | // by the completion token. This completion handler matches the asynchronous |
| 70 | // operation's completion handler signature, which in this example is: |
| 71 | // |
| 72 | // void(boost::system::error_code error) |
| 73 | // |
| 74 | // The initiation function object also receives any additional arguments |
| 75 | // required to start the operation. (Note: We could have instead passed these |
| 76 | // arguments in the lambda capture set. However, we should prefer to |
| 77 | // propagate them as function call arguments as this allows the completion |
| 78 | // token to optimise how they are passed. For example, a lazy future which |
| 79 | // defers initiation would need to make a decay-copy of the arguments, but |
| 80 | // when using a simple callback the arguments can be trivially forwarded |
| 81 | // straight through.) |
| 82 | auto initiation = [](auto&& completion_handler, |
| 83 | tcp::socket& socket, std::unique_ptr<std::string> encoded_message) |
| 84 | { |
| 85 | // In this example, the composed operation's intermediate completion |
| 86 | // handler is implemented as a hand-crafted function object, rather than |
| 87 | // using a lambda or std::bind. |
| 88 | struct intermediate_completion_handler |
| 89 | { |
| 90 | // The intermediate completion handler holds a reference to the socket so |
| 91 | // that it can obtain the I/O executor (see get_executor below). |
| 92 | tcp::socket& socket_; |
| 93 | |
| 94 | // The allocated buffer for the encoded message. The std::unique_ptr |
| 95 | // smart pointer is move-only, and as a consequence our intermediate |