| 36 | |
| 37 | template <typename CompletionToken> |
| 38 | auto async_write_message(tcp::socket& socket, |
| 39 | const char* 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, const char* message) |
| 84 | { |
| 85 | // The async_write operation has a completion handler signature of: |
| 86 | // |
| 87 | // void(boost::system::error_code error, std::size n) |
| 88 | // |
| 89 | // This differs from our operation's signature in that it is also passed |
| 90 | // the number of bytes transferred as an argument of type std::size_t. We |
| 91 | // will adapt our completion handler to async_write's completion handler |
| 92 | // signature by using std::bind, which drops the additional argument. |
| 93 | // |
| 94 | // However, it is essential to the correctness of our composed operation |
| 95 | // that we preserve the executor of the user-supplied completion handler. |