@@ -11806,30 +11806,54 @@
1180611806are general-purpose memory resources having the following qualities:
1180711807\begin{itemize}
1180811808\item
11809- Each resource frees its allocated memory on destruction,
11810- even if \tcode{deallocate} has not been called for some of the allocated blocks.
11809+ A pool resource has an \defn{upstream memory resource},
11810+ supplied on construction, which is used to allocate memory that
11811+ the pool resource subdivides to satisfy calls to its own
11812+ \tcode{do_allocate} member.
11813+
11814+ \item
11815+ A \defn{chunk} is a region of storage allocated
11816+ from the upstream memory resource. A pool resource divides
11817+ each chunk into one or more blocks of the same block size.
11818+ Different chunks can have different block sizes, and different
11819+ numbers of blocks.
11820+
11821+ \item
11822+ A \defn{pool} is a collection of chunks that all have the same
11823+ block size. Each pool resource contains a collection of pools
11824+ with different block sizes.
11825+
11826+ \item
11827+ On destruction, a pool resource frees all the memory it obtained from
11828+ its upstream memory resource by calling the upstream resource's
11829+ \tcode{deallocate} function.
11830+ \begin{note}
11831+ This frees all memory returned by the pool resource's \tcode{do_allocate}
11832+ function, even if \tcode{do_deallocate} has not been called for some
11833+ of the allocated blocks.
11834+ \end{note}
11835+
1181111836\item
11812- A pool resource consists of a collection of \defn{pools},
11813- serving requests for different block sizes.
11814- Each individual pool manages a collection of \defn{chunks}
11815- that are in turn divided into blocks of uniform size,
11816- returned via calls to \tcode{do_allocate}.
1181711837Each call to \tcode{do_allocate(size, alignment)} is dispatched
11818- to the pool serving the smallest blocks accommodating at least \tcode{size} bytes.
11838+ to the pool serving the smallest blocks accommodating at \tcode{size} bytes
11839+ and are aligned to a multiple of \tcode{alignment}.
11840+
1181911841\item
1182011842When a particular pool is exhausted,
1182111843allocating a block from that pool results in the allocation
11822- of an additional chunk of memory from the \defn{ upstream allocator}
11823- (supplied at construction), thus replenishing the pool.
11844+ of an additional chunk from the upstream memory resource,
11845+ thus replenishing the pool.
1182411846With each successive replenishment,
1182511847the chunk size obtained increases geometrically.
1182611848\begin{note}
1182711849By allocating memory in chunks,
1182811850the pooling strategy increases the chance that consecutive allocations
1182911851will be close together in memory.\end{note}
11852+
1183011853\item
11831- Allocation requests that exceed the largest block size of any pool
11832- are fulfilled directly from the upstream allocator.
11854+ Allocation requests that exceed the largest block size and/or alignment
11855+ of any pool are fulfilled directly from the upstream allocator.
11856+
1183311857\item
1183411858A \tcode{pool_options} struct may be passed to the pool resource constructors
1183511859to tune the largest block size and the maximum chunk size.
1192511949\begin{itemdescr}
1192611950\pnum
1192711951The maximum number of blocks that will be allocated at once
11928- from the upstream memory resource\iref{mem.res.monotonic.buffer }
11952+ from the upstream memory resource\iref{mem.res.pool.overview }
1192911953to replenish a pool.
1193011954If the value of \tcode{max_blocks_per_chunk} is zero or
1193111955is greater than an \impldef{largest supported value to configure the maximum number of blocks to replenish a pool}
0 commit comments