Skip to content

Commit 44cc202

Browse files
committed
[mem.res.pool.overview] add proper definitions of terms
Update cross-reference in [mem.res.pool.options] to refer to [mem.res.pool.overview]. Fixes #1258
1 parent 7066a90 commit 44cc202

File tree

1 file changed

+37
-13
lines changed

1 file changed

+37
-13
lines changed

source/utilities.tex

Lines changed: 37 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -11806,30 +11806,54 @@
1180611806
are 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}.
1181711837
Each 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
1182011842
When a particular pool is exhausted,
1182111843
allocating 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.
1182411846
With each successive replenishment,
1182511847
the chunk size obtained increases geometrically.
1182611848
\begin{note}
1182711849
By allocating memory in chunks,
1182811850
the pooling strategy increases the chance that consecutive allocations
1182911851
will 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
1183411858
A \tcode{pool_options} struct may be passed to the pool resource constructors
1183511859
to tune the largest block size and the maximum chunk size.
@@ -11925,7 +11949,7 @@
1192511949
\begin{itemdescr}
1192611950
\pnum
1192711951
The 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}
1192911953
to replenish a pool.
1193011954
If the value of \tcode{max_blocks_per_chunk} is zero or
1193111955
is greater than an \impldef{largest supported value to configure the maximum number of blocks to replenish a pool}

0 commit comments

Comments
 (0)