Add a chapter on asio compliance - per operation cancellation

Summary: related to T12804

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

Differential Revision: https://repo.mireo.local/D28516

example/timeout_with_awaitable_operators.cpp

@@ -0,0 +1,66 @@
+//[timeout_with_awaitable_operators
+#include <iostream>
+
+#include <boost/asio/as_tuple.hpp>
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/co_spawn.hpp>
+#include <boost/asio/detached.hpp>
+#include <boost/asio/steady_timer.hpp>
+#include <boost/asio/use_awaitable.hpp>
+#include <boost/asio/experimental/awaitable_operators.hpp>
+#include <boost/asio/experimental/parallel_group.hpp>
+#include <boost/asio/ip/tcp.hpp>
+
+#include <async_mqtt5.hpp>
+
+#ifdef BOOST_ASIO_HAS_CO_AWAIT
+
+// Modified completion token that will prevent co_await from throwing exceptions.
+constexpr auto use_nothrow_awaitable = boost::asio::as_tuple(boost::asio::use_awaitable);
+
+using client_type = async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket>;
+
+boost::asio::awaitable<void> send_over_mqtt(client_type& client, const std::string& message) {
+	client.brokers("<your-mqtt-broker>", 1883)
+		.async_run(boost::asio::detached);
+
+	auto&& [pec, prc, puback_props] = co_await client.async_publish<async_mqtt5::qos_e::at_least_once>(
+		"<your-mqtt-topic>", message,
+		async_mqtt5::retain_e::no, async_mqtt5::publish_props {},
+		use_nothrow_awaitable
+	);
+
+	co_await client.async_disconnect(use_nothrow_awaitable);
+}
+
+int main() {
+	boost::asio::io_context ioc;
+
+	co_spawn(ioc, [&ioc]() -> boost::asio::awaitable<void> {
+		// Construct the Client.
+		async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc);
+
+		// Construct the timer.
+		boost::asio::steady_timer timer(ioc, std::chrono::seconds(5));
+
+		using namespace boost::asio::experimental::awaitable_operators;
+		auto res = co_await (
+			send_over_mqtt(client, "Hello world!") ||
+			timer.async_wait(use_nothrow_awaitable)
+		);
+
+		// The timer expired first. The client is cancelled.
+		if (res.index() == 1)
+			std::cout << "Send over MQTT timed out!" << std::endl;
+		// send_over_mqtt completed first. The timer is cancelled.
+		else
+			std::cout << "Send over MQTT completed!" << std::endl;
+		
+	}, boost::asio::detached);
+
+	ioc.run();
+}
+
+#endif
+
+//]

example/timeout_with_parallel_group.cpp

@@ -0,0 +1,63 @@
+//[timeout_with_parallel_group
+#include <iostream>
+
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/deferred.hpp>
+#include <boost/asio/steady_timer.hpp>
+#include <boost/asio/experimental/parallel_group.hpp>
+#include <boost/asio/ip/tcp.hpp>
+
+#include <async_mqtt5.hpp>
+
+int main() {
+	boost::asio::io_context ioc;
+
+	// Construct the Client.
+	async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> client(ioc);
+
+	// Construct the timer.
+	boost::asio::steady_timer timer(ioc, std::chrono::seconds(5));
+
+	client.brokers("<your-mqtt-broker>", 1883)
+		.async_run(boost::asio::detached);
+
+	// Subscribe to a Topic.
+	client.async_subscribe(
+		{ "<your-mqtt-topic>" }, async_mqtt5::subscribe_props {},
+		[](async_mqtt5::error_code ec, std::vector<async_mqtt5::reason_code> rcs, async_mqtt5::suback_props) {
+			std::cout << "[subscribe ec]: " << ec.message() << std::endl;
+			std::cout << "[subscribe rc]: " << rcs[0].message() << std::endl;
+		}
+	);
+
+	// Create a parallel group to wait up to 5 seconds to receive a message
+	// using client.async_receive(...).
+	boost::asio::experimental::make_parallel_group(
+		timer.async_wait(boost::asio::deferred),
+		client.async_receive(boost::asio::deferred)
+	).async_wait(
+		boost::asio::experimental::wait_for_one(),
+		[&client](
+			std::array<std::size_t, 2> ord, // Completion order
+			async_mqtt5::error_code /* timer_ec */, // timer.async_wait(...) handler signature
+			// client.async_receive(...) handler signature
+			async_mqtt5::error_code receive_ec, 
+			std::string topic, std::string payload, async_mqtt5::publish_props /* props */
+		) {
+			if (ord[0] == 1) {
+				std::cout << "Received a message!" << std::endl;
+				std::cout << "[receive ec]: " << receive_ec.message() << std::endl;
+				std::cout << "[receive topic]: " << topic << std::endl;
+				std::cout << "[receive payload]: " << payload << std::endl;
+			}
+			else
+				std::cout << "Timed out! Did not receive a message within 5 seconds." << std::endl;
+
+			client.cancel();
+		}
+	);
+
+	ioc.run();
+}
+
+//]