diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index 3d31a23..6d76611 100644 --- a/doc/qbk/00_main.qbk +++ b/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] diff --git a/doc/qbk/05_optimising_communication.qbk b/doc/qbk/05_optimising_communication.qbk index f8950a5..7990d43 100644 --- a/doc/qbk/05_optimising_communication.qbk +++ b/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] diff --git a/doc/qbk/07_asio_compliance.qbk b/doc/qbk/07_asio_compliance.qbk index 1303c2a..1fe1061 100644 --- a/doc/qbk/07_asio_compliance.qbk +++ b/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] diff --git a/doc/qbk/08_allocators.qbk b/doc/qbk/08_allocators.qbk new file mode 100644 index 0000000..efb52b4 --- /dev/null +++ b/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] diff --git a/doc/qbk/08_executors.qbk b/doc/qbk/10_executors.qbk similarity index 100% rename from doc/qbk/08_executors.qbk rename to doc/qbk/10_executors.qbk diff --git a/doc/qbk/10_examples.qbk b/doc/qbk/15_examples.qbk similarity index 100% rename from doc/qbk/10_examples.qbk rename to doc/qbk/15_examples.qbk