This example demonstrates how to use mqtt_client asynchrous functions with C++20 coroutines using boost::asio::use_awaitable.

use_awaitable

In this section, each asynchronous function is invoked with boost::asio::use_awaitable completion token. When using this completion token, co_await will throw exceptions instead of returning an error code. If you do not wish to throw exceptions, refer to the following use_nothrow_awaitable section.

Publish

// Publish an Application Message with QoS 0.
// The handler signature for this function is void (error_code).
// However, when using asio::use_awaitable as a completion token,
// the error_code is not returned but thrown as an exception if an error occurrs.
co_await client.async_publish<async_mqtt5::qos_e::at_most_once>(
	"test/mqtt-test", "Hello world!",
	async_mqtt5::retain_e::yes, async_mqtt5::publish_props {},
	asio::use_awaitable
);

// Publish an Application Message with QoS 1.
// The handler signature for this function is void (error_code, reason_code, puback_props).
// With asio::use_awaitable as a completion token, the co_await will return reason_code and puback_props.
auto [puback_rc, puback_props] = co_await client.async_publish<async_mqtt5::qos_e::at_least_once>(
	"test/mqtt-test", "Hello world!",
	async_mqtt5::retain_e::yes, async_mqtt5::publish_props {},
	asio::use_awaitable
);

// Publish an Application Message with QoS 2.
// The handler signature for this function is void (error_code, reason_code, pubcomp_props).
// With asio::use_awaitable as a completion token, the co_await will return reason_code and pubcomp_props.
auto [pubcomp_rc, pubcomp_props] = co_await client.async_publish<async_mqtt5::qos_e::exactly_once>(
	"test/mqtt-test", "Hello world!",
	async_mqtt5::retain_e::yes, async_mqtt5::publish_props {},
	asio::use_awaitable
);

Subscribe

// Subscribe to a single Topic.
// The handler signature for this function is void (error_code, std::vector<reason_code>, suback_props).
// With asio::use_awaitable as a completion token, the co_await
// will return std::vector<reason_code> and suback_props.
auto [sub_codes, sub_props] = co_await client.async_subscribe(
	{ "test/mqtt-test", { async_mqtt5::qos_e::exactly_once } },
	async_mqtt5::subscribe_props {},  asio::use_awaitable
);

Receive

// Receive an Application Message.
// The co_await call will return std::string (topic), std::string (payload) and publish_props.
// Note: the coroutine will be suspended until an Application Message is ready to be received
// or an error has occurred. In theory, the coroutine could be suspended indefinitely.
// Avoid calling this if you have not successfully subscribed to a Topic.
auto [topic, payload, publish_props] = co_await client.async_receive(asio::use_awaitable);

Unsubscribe

// Unsubscribe from the Topic.
// The handler signature for this function is void (error_code, std::vector<reason_code>, unsuback_props).
// With asio::use_awaitable as a completion token, the co_await
// will return std::vector<reason_code> and unsuback_props.
auto [unsub_codes, unsub_props] = co_await client.async_unsubscribe(
	"test/mqtt-test", async_mqtt5::unsubscribe_props {},
	asio::use_awaitable
);

Disconnect

// Disconnect the Client.
// With asio::use_awaitable as a completion token and void (error_code) as the completion signature,
// the co_await has nothing to return.
co_await client.async_disconnect(
	async_mqtt5::disconnect_rc_e::disconnect_with_will_message,
	async_mqtt5::disconnect_props {},
	asio::use_awaitable
);

use_nothrow_awaitable

The following examples will use a modified completion token. Using this completion token instead of boost::asio::use_awaitable will prevent co_await from throwing exceptions. Instead, co_await will return the error code along with other values specified in the handler signature.

constexpr auto use_nothrow_awaitable = asio::as_tuple(asio::use_awaitable);

Publish

async_mqtt5::error_code ec;
async_mqtt5::reason_code rc;

std::tie(ec) = co_await client.async_publish<async_mqtt5::qos_e::at_most_once>(
	"test/mqtt-test", "Hello world!",
	async_mqtt5::retain_e::yes, async_mqtt5::publish_props {},
	use_nothrow_awaitable
);

async_mqtt5::puback_props puback_props;
std::tie(ec, rc, puback_props) = co_await client.async_publish<async_mqtt5::qos_e::at_least_once>(
	"test/mqtt-test", "Hello world!",
	async_mqtt5::retain_e::yes, async_mqtt5::publish_props {},
	use_nothrow_awaitable
);

async_mqtt5::pubcomp_props pubcomp_props;
std::tie(ec, rc, pubcomp_props) = co_await client.async_publish<async_mqtt5::qos_e::exactly_once>(
	"test/mqtt-test", "Hello world!",
	async_mqtt5::retain_e::yes, async_mqtt5::publish_props {},
	use_nothrow_awaitable
);

Subscribe

std::vector<async_mqtt5::reason_code> rcs;
async_mqtt5::suback_props suback_props;
std::tie(ec, rcs, suback_props) = co_await client.async_subscribe(
	{ "test/mqtt-test", { async_mqtt5::qos_e::exactly_once } },
	async_mqtt5::subscribe_props {}, use_nothrow_awaitable
);

Receive

std::string topic, payload;
async_mqtt5::publish_props publish_props;
std::tie(ec, topic, payload, publish_props) = co_await client.async_receive(use_nothrow_awaitable);

Unsubscribe

async_mqtt5::unsuback_props unsuback_props;
std::tie(ec, rcs, unsuback_props) = co_await client.async_unsubscribe(
	std::vector<std::string>{ "test/mqtt-test" }, async_mqtt5::unsubscribe_props {},
	use_nothrow_awaitable
);

Disconnect

std::tie(ec) = co_await client.async_disconnect(
	async_mqtt5::disconnect_rc_e::disconnect_with_will_message,
	async_mqtt5::disconnect_props {},
	use_nothrow_awaitable
);