| 35 | |
| 36 | template <typename CompletionToken> |
| 37 | auto async_write_message(tcp::socket& socket, |
| 38 | const char* message, bool allow_partial_write, |
| 39 | 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 void. |
| 48 | // However, when the completion token is boost::asio::yield_context (used for |
| 49 | // stackful coroutines) the return type would be std::size_t, and when the |
| 50 | // completion token is boost::asio::use_future it would be std::future<std::size_t>. |
| 51 | // When the completion token is boost::asio::deferred, the return type differs for |
| 52 | // each asynchronous operation. |
| 53 | // |
| 54 | // In C++14 we can omit the return type as it is automatically deduced from |
| 55 | // the return type of boost::asio::async_initiate. |
| 56 | { |
| 57 | // In addition to determining the mechanism by which an asynchronous |
| 58 | // operation delivers its result, a completion token also determines the time |
| 59 | // when the operation commences. For example, when the completion token is a |
| 60 | // simple callback the operation commences before the initiating function |
| 61 | // returns. However, if the completion token's delivery mechanism uses a |
| 62 | // future, we might instead want to defer initiation of the operation until |
| 63 | // the returned future object is waited upon. |
| 64 | // |
| 65 | // To enable this, when implementing an asynchronous operation we must |
| 66 | // package the initiation step as a function object. The initiation function |
| 67 | // object's call operator is passed the concrete completion handler produced |
| 68 | // by the completion token. This completion handler matches the asynchronous |
| 69 | // operation's completion handler signature, which in this example is: |
| 70 | // |
| 71 | // void(boost::system::error_code error, std::size_t) |
| 72 | // |
| 73 | // The initiation function object also receives any additional arguments |
| 74 | // required to start the operation. (Note: We could have instead passed these |
| 75 | // arguments in the lambda capture set. However, we should prefer to |
| 76 | // propagate them as function call arguments as this allows the completion |
| 77 | // token to optimise how they are passed. For example, a lazy future which |
| 78 | // defers initiation would need to make a decay-copy of the arguments, but |
| 79 | // when using a simple callback the arguments can be trivially forwarded |
| 80 | // straight through.) |
| 81 | auto initiation = [](auto&& completion_handler, tcp::socket& socket, |
| 82 | const char* message, bool allow_partial_write) |
| 83 | { |
| 84 | if (allow_partial_write) |
| 85 | { |
| 86 | // When delegating to an underlying operation we must take care to |
| 87 | // perfectly forward the completion handler. This ensures that our |
| 88 | // operation works correctly with move-only function objects as |
| 89 | // callbacks. |
| 90 | return socket.async_write_some( |
| 91 | boost::asio::buffer(message, std::strlen(message)), |
| 92 | std::forward<decltype(completion_handler)>(completion_handler)); |
| 93 | } |
| 94 | else |