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