Boost asio completion tokens

[jonesmz]

An enhancement to the mqtt_cpp api to support different styles of async programming.

https://www.boost.org/doc/libs/1_65_0/libs/fiber/doc/html/fiber/callbacks/then_there_s____boost_asio__.html https://www.boost.org/doc/libs/1_70_0/doc/html/boost_asio/reference/async_completion.html https://github.com/yandex/ozo/blob/master/include/ozo/asio.h

The way that completion tokens work is that we would have each async function take a template parameter CompletionToken instead of the callback function,

The CompletionToken parameter would then be inspected by the boost async_completion<> type trait to determine things like return type (e.g. might return an std::future, or whatever else), and then a handler to call when the async operation is finished (might not be the thing passed in, for example).

The return object would be returned at the end of the call stack for initiating the async operation. E.g. it would be returned when we push the message to send onto the queue of outgoing messages. The handler would be called the same way we currently call it, when the message has been sent over the wire.

[redboltz]

Let me clarify about the completion token.

1. The client codes that call the existing async APIs that have void return type with async_handler_t parameter don't need to update. Is that right? I think that async_handler_t meets the completion token concept.
2. Does the type of completion token affect the async API return type? It it does, the following async APIs need to update (or removed) ? What kind of updates are needed for the following APIs?

• bool async_*(packet_id_t, ...)
  • This function register packet_id internally and if it has already been registered, then return false.
• packet_id_t async_*(...)
  • This function acquire packet_id internally and if it fails, then throw exception, otherwise return the acquired packet_id.

[jonesmz]

The client codes that call the existing async APIs that have void return type with async_handler_t parameter don't need to update. Is that right? I think that async_handler_t meets the completion token concept.

Yes.

Does the type of completion token affect the async API return type? It it does, the following async APIs need to update (or removed) ? What kind of updates are needed for the following APIs?

Yes. The completion token specifies the return type.

See https://github.com/redboltz/mqtt_cpp/issues/534 on how we can make this better anyway.

[redboltz]

One more thing. We need to check Boost.Beast support the completion tokens the same as Boost.Asio.

[jonesmz]

Most of the documentation I was reading for completion tokens came from boost.beast, but I agree it is important to confirm for websocket support.