mirror of
https://github.com/boostorg/asio.git
synced 2026-01-23 05:22:08 +00:00
66 lines
2.9 KiB
Plaintext
66 lines
2.9 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003-2025 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
|
/
|
|
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
/]
|
|
|
|
[section:allocators Allocators]
|
|
|
|
Every asynchronous agent has an associated ['allocator]. An agent's allocator
|
|
is an interface used by the agent's asynchronous operations to obtain
|
|
['per-operation stable memory] resources (POSMs). This name reflects the fact
|
|
that the memory is per-operation because the memory is only retained for the
|
|
lifetime of that operation, and stable, because the memory is guaranteed to be
|
|
available at that location throughout the operation.
|
|
|
|
Asynchronous operations may utilise POSMs in a number of different ways:
|
|
|
|
* The operation doesn't require any POSMs. For example, the operation wraps an
|
|
existing API that performs its own memory management, or is copying the long
|
|
lived state into existing memory like a circular buffer.
|
|
|
|
* The operation uses a single, fixed-size POSM for as long as the operation is
|
|
outstanding. For example, the operation stores some state in a linked list.
|
|
|
|
* The operation uses a single, runtime-sized POSM. For example, the operation
|
|
stores a copy of a user-supplied buffer, or a runtime-sized array of iovec
|
|
structures.
|
|
|
|
* The operation uses multiple POSMs concurrently. For example, a fixed size
|
|
POSM for a linked list plus a runtime-sized POSM for a buffer.
|
|
|
|
* The operation uses multiple POSMs serially, which may vary in size.
|
|
|
|
Associated allocators allow users to treat POSM optimisation as a cross-cutting
|
|
concern to the composition of asynchronous operations. Furthermore, using
|
|
allocators as the interface to obtain POSMs grant substantial flexibility to
|
|
both the implementers and users of asynchronous operations:
|
|
|
|
* Users can ignore the allocator and accept whatever default strategy is
|
|
employed by the application.
|
|
|
|
* Implementers can ignore the allocator, especially if the operation is not
|
|
considered performance-sensitive.
|
|
|
|
* Users can co-locate POSMs for related asynchronous operations, for better
|
|
locality of reference.
|
|
|
|
* For compositions that involve serial POSMs of different sizes, memory usage
|
|
need only be as great as the currently extant POSM. For example, consider a
|
|
composition that contains a short-lived operation that uses large POSMs
|
|
(connection establishment and handshake) followed by a long-lived operation
|
|
that uses small POSMs (transferring data to and from the peer).
|
|
|
|
As noted previously, all resources must be released prior to calling the
|
|
completion handler. This enables memory to be recycled for subsequent
|
|
asynchronous operations within an agent. This allows applications with
|
|
long-lived asynchronous agents to have no hot-path memory allocations, even
|
|
though the user code is unaware of associated allocators.
|
|
|
|
[heading See Also]
|
|
|
|
[link boost_asio.overview.core.allocation Custom Memory Allocation].
|
|
|
|
[endsect]
|