Add a chapter on asio compliance - allocators

Summary: related to T12804

Reviewers: ivica

Reviewed By: ivica

Subscribers: miljen, iljazovic

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

doc/qbk/00_main.qbk

@@ -42,6 +42,8 @@
 [def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]]
 [def __Beast__ [@boost:/libs/beast/index.html Boost.Beast]]
 [def __ASIO_PER_OP_CANCELLATION__ [@boost:/doc/html/boost_asio/overview/core/cancellation.html Per-Operation Cancellation]]
+[def __ASIO_ALLOCATORS__ [@boost:/doc/html/boost_asio/overview/model/allocators.html Allocators]]
+[def __ASIO_CUSTOM_MEMORY_ALLOCATION__ [@boost:/doc/html/boost_asio/overview/core/allocation.html Custom Memory Allocation]]
 [def __ASIO_PARALLEL_GROUP__ [@boost:/doc/html/boost_asio/overview/composition/parallel_group.html Co-ordinating Parallel Operations]]
 [def __IOC__ [@boost:doc/html/boost_asio/reference/io_context.html `boost::asio::io_context`]]
 [def __POST__ [@boost:doc/html/boost_asio/reference/post.html `boost::asio::post`]]
@@ -119,7 +121,7 @@
 [include 06_disconnecting_the_client.qbk]
 [include 07_asio_compliance.qbk]
 
-[include 10_examples.qbk]
+[include 15_examples.qbk]
 
 [include examples/Examples.qbk]
 

doc/qbk/05_optimising_communication.qbk

@@ -34,7 +34,7 @@ Source: [link async_mqtt5.multiflight_client multiflight_client.cpp]
 
 [endsect] [/multiflight]
 
-[section:packet_queing Efficient bandwidth usage with packet queing]
+[section:packet_queuing Efficient bandwidth usage with packet queuing]
 
 The __Client__ employs a strategic queuing mechanism crucial in optimising network usage and performance for the user's requests.
 This mechanism bundles multiple MQTT packets for transmission within a single TCP packet whenever feasible 
@@ -54,7 +54,7 @@ As a result, in the [link async_mqtt5.multiflight_client multiflight_client.cpp]
 the __Client__ will transmit all `5` __PUBLISH__ packets in a single TCP packet
 if possible [footnote The Broker's `Receive Maximum` is equal to or greater than `5`.].
 
-[endsect] [/packet_queing]
+[endsect] [/packet_queuing]
 
 [section:packet_ordering Packet ordering]
 

doc/qbk/07_asio_compliance.qbk

@@ -9,11 +9,14 @@ Every asynchronous operation in __Asio__ has associated characteristics that spe
 This section expands further into the roles of allocators,
 cancellation slots, and executors, highlighting their integration and usage within the __Client__.
 
+* See [link async_mqtt5.asio_compliance.allocators Allocators] for more information about how the 
+__Client__ supports and uses associated allocators.
 * See [link async_mqtt5.asio_compliance.per_op_cancellation Per-Operation Cancellation] for more information about how
 asynchronous operations within the __Client__ support cancellation.
 * See [link async_mqtt5.asio_compliance.executors Executors] for more information about executors.
 
-[include 08_executors.qbk]
+[include 08_allocators.qbk]
 [include 09_per_op_cancellation.qbk]
+[include 10_executors.qbk]
 
 [endsect] [/asio_compliance]

doc/qbk/08_allocators.qbk

@@ -0,0 +1,22 @@
+[section:allocators Allocators]
+
+Every asynchronous operation has an associated allocator
+designed to provide the operation with a consistent and stable memory source for the duration of its execution.
+This allocated memory, referred to as per-operation stable memory resources (POSMs),
+remains retained for the lifetime of the operation, ensuring its availability whenever needed. 
+Asynchronous operations may utilise POSMs in numerous ways.
+See __ASIO_ALLOCATORS__ and __ASIO_CUSTOM_MEMORY_ALLOCATION__ for more information. 
+
+The __Client__ supports and utilises allocators associated with `async_xxx`'s handlers
+to store the state associated with the operation.
+Specifically, the allocator is used to reserve memory for MQTT Control Packet bytes 
+(__PUBLISH__, __SUBSCRIBE__,...) created by each `async_xxx` operation request.
+Moreover, the __Client__'s internal packet queue
+(described in the section ['Efficient bandwidth usage with packet queuing] in [link async_mqtt5.optimising_communication Optimising communication])
+associates the allocator of the first packet in the queue to the low-level __Asio__ function
+`async_write` on the transport layer.
+
+Lastly, the __Client__ uses [@boost:doc/html/boost_asio/reference/recycling_allocator.html `boost::asio::recycling_allocator`]
+to allocate memory for its internal operations and components.
+
+[endsect][/allocators]