mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-01-17 08:31:09 -08:00
200 lines
11 KiB
ReStructuredText
200 lines
11 KiB
ReStructuredText
.. index::
|
|
single: pool class; choosing
|
|
|
|
.. _pool-choose:
|
|
|
|
Choosing a pool class
|
|
=====================
|
|
|
|
This section contains a simple procedure for choosing a :term:`pool
|
|
class` based on the properties of the data you plan to store in
|
|
it. The MPS works well if you can segregate your data into a variety
|
|
of pools, choosing the most appropriate pool class for each.
|
|
|
|
.. note::
|
|
|
|
Pool classes can differ in many ways not considered here: speed,
|
|
vulnerability to fragmentation, control overhead, and so on. This
|
|
procedure gives you a decent recommendation, but an expert in the
|
|
MPS might be able to make a better recommendation. And if no pool
|
|
class in the open source MPS exactly matches your needs, then it
|
|
is possible to develop new pool classes. See :ref:`pool-writing`.
|
|
|
|
First, answer these questions about your data:
|
|
|
|
1. Do you need the MPS to :term:`automatically <automatic memory
|
|
management>` :term:`reclaim` :term:`unreachable` blocks?
|
|
|
|
2. Is it acceptable for the MPS to :term:`move <moving memory
|
|
manager>` blocks in memory and to place :term:`barriers (1)` on
|
|
blocks? (For example, it might not be acceptable to move a block if
|
|
it has been passed to :term:`foreign code` that remembered its
|
|
location.)
|
|
|
|
3. Do your blocks contain :term:`references` to blocks stored in
|
|
automatically managed pools (including references to other blocks
|
|
in the same pool, if it's automatically managed)? And if so, are
|
|
these references :term:`exact <exact reference>`, :term:`ambiguous
|
|
<ambiguous reference>` or :term:`weak <weak reference (1)>`?
|
|
|
|
Second, look up your answers in this table to find the recommended
|
|
pool class to use:
|
|
|
|
========== ====================== =========== ====================================
|
|
Automatic? Movable & protectable? References? Use this pool class
|
|
========== ====================== =========== ====================================
|
|
yes yes none :ref:`pool-amcz`
|
|
yes yes exact :ref:`pool-amc`
|
|
yes yes ambiguous nothing suitable
|
|
yes yes weak :ref:`pool-awl`
|
|
yes no none :ref:`pool-lo`
|
|
yes no exact :ref:`pool-ams`
|
|
yes no ambiguous nothing suitable
|
|
yes no weak nothing suitable
|
|
no *any* none :ref:`pool-mvt`
|
|
no *any* exact :ref:`pool-mvt` [1]_
|
|
no *any* ambiguous :ref:`pool-mvt` [1]_
|
|
no *any* weak :ref:`pool-mvt` [1]_
|
|
========== ====================== =========== ====================================
|
|
|
|
.. note::
|
|
|
|
.. [1] :ref:`pool-mvt` doesn't scan for references, but you can
|
|
work around this by registering your blocks as
|
|
:term:`roots` (with the appropriate :term:`rank`) just
|
|
after they are allocated, and deregistering them just
|
|
before freeing them.
|
|
|
|
|
|
.. Sources:
|
|
|
|
`<https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/guide/pool-classes/>`_
|
|
|
|
.. index::
|
|
single: pool class; table of properties
|
|
|
|
.. _pool-properties:
|
|
|
|
Pool class properties
|
|
=====================
|
|
|
|
This table summarizes the properties of each :term:`pool class`
|
|
provided by the open source MPS. For "block" properties, "yes" means
|
|
that the property holds for *all* blocks allocated from the pool. An
|
|
entry "---" indicates that a property makes no sense for a pool class:
|
|
for example, if blocks in a pool may not contain :term:`references`,
|
|
it makes no sense to ask whether they may contain :term:`weak
|
|
references (1)`.
|
|
|
|
|
|
============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== =====
|
|
Property AMC AMCZ AMS AWL LO MFS MV MVFF MVT SNC
|
|
============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== =====
|
|
Supports :c:func:`mps_alloc`? no no no no no yes yes yes no no
|
|
Supports :c:func:`mps_free`? no no no no no yes yes yes yes no
|
|
Supports allocation points? yes yes yes yes yes no no yes yes yes
|
|
Supports allocation frames? yes yes yes yes yes no no yes yes yes
|
|
Supports segregated allocation caches? no no no no no yes yes yes no no
|
|
Timing of collections? [2]_ auto auto auto auto auto --- --- --- --- ---
|
|
May contain references? [3]_ yes no yes yes no no no no no yes
|
|
May contain exact references? [4]_ yes --- yes yes --- --- --- --- --- yes
|
|
May contain ambiguous references? [4]_ no --- no no --- --- --- --- --- no
|
|
May contain weak references? [4]_ no --- no yes --- --- --- --- --- no
|
|
Allocations fixed or variable in size? var var var var var fixed var var var var
|
|
Alignment? [5]_ conf conf conf conf conf [6]_ [6]_ [7]_ [6]_ conf
|
|
Dependent objects? [8]_ no --- no yes --- --- --- --- --- no
|
|
May use remote references? [9]_ no --- no no --- --- --- --- --- no
|
|
Blocks are automatically managed? [10]_ yes yes yes yes yes no no no no no
|
|
Blocks are manually managed? [10]_ no no no no no yes yes yes yes yes
|
|
Blocks are scanned? [11]_ yes no yes yes no no no no no yes
|
|
Blocks support base pointers only? [12]_ yes yes yes yes yes --- --- --- --- yes
|
|
Blocks support internal pointers? [12]_ no no no no no --- --- --- --- no
|
|
Blocks may be protected by barriers? yes no yes yes yes no no no no yes
|
|
Blocks may move? yes yes no no no no no no no no
|
|
Blocks may be finalized? yes yes yes yes yes no no no no no
|
|
Blocks must be formatted? [11]_ yes yes yes yes yes no no no no yes
|
|
Blocks may belong to format auto-header? yes yes yes yes yes --- --- --- --- no
|
|
============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== =====
|
|
|
|
.. note::
|
|
|
|
.. [2] "Timing of collections" is "auto" if :term:`garbage collection`
|
|
is under the control of the MPS, which decides when collection
|
|
should take place and performs it :term:`automatically
|
|
<automatic memory management>` and :term:`incrementally
|
|
<incremental garbage collection>`.
|
|
|
|
.. [3] The references in question are references to blocks in
|
|
:term:`automatically managed <automatic memory management>`
|
|
:term:`pools`.
|
|
|
|
.. [4] Pools "may contain :term:`ambiguous <ambiguous reference>` /
|
|
:term:`exact <exact reference>` / :term:`weak <weak
|
|
reference (1)>` references" if the references that the client
|
|
program fixes during scanning may include references of the
|
|
indicated :term:`rank`.
|
|
|
|
.. [5] "Alignment" is "conf" if the client program may specify
|
|
:term:`alignment` for each pool.
|
|
|
|
.. [6] The alignment of blocks allocated from :ref:`pool-mv` and
|
|
:ref:`pool-mvt` pools is platform-dependent.
|
|
|
|
.. [7] :ref:`pool-mvff` pools have configurable alignment, but it
|
|
may not be smaller than the :term:`natural alignment` for
|
|
the :term:`platform` (see :c:macro:`MPS_PF_ALIGN`).
|
|
|
|
.. [8] In pools with this property, each object may specify an
|
|
:term:`dependent object` which the client program
|
|
guarantees will be accessible during the scanning of the
|
|
first object. This may be used in the implementation of
|
|
:term:`weak hash tables`.
|
|
|
|
.. [9] "Remote references" are references that are stored outside the
|
|
block to which they logically belong (for example, in some kind
|
|
of auxiliary table). A pool containing remote references cannot
|
|
rely on a :term:`write barrier` to detect changed references.
|
|
|
|
.. [10] Blocks are "automatically managed" if they may be
|
|
automatically discarded when the MPS determines that they
|
|
are unreachable; they are "manually managed" if they can be
|
|
discarded when the :term:`client program` requests it. Note
|
|
that these properties are not mutually exclusive, although
|
|
the MPS does not provide a pool class that satisfies both.
|
|
|
|
.. [11] Blocks "are scanned" if the MPS :term:`scans` them for
|
|
references; blocks "must be formatted" if they are
|
|
described to the MPS by an :term:`object format`. At
|
|
present, the MPS only knows how to scan blocks using the
|
|
:term:`scan method` from an object format, but the MPS
|
|
design does not preclude pools that scan unformatted
|
|
blocks.
|
|
|
|
.. [12] A block "supports internal pointers" if a pointer to any
|
|
location within the block is considered to be a reference
|
|
to the block. It "supports base pointers only" if only a
|
|
pointer to the base of the block (or, if the block belongs
|
|
to an object format of variant auto-header, a pointer just
|
|
past the end of the header) is considered to be a reference
|
|
to the block.
|
|
|
|
|
|
.. index::
|
|
single: pool class; writing
|
|
|
|
.. _pool-writing:
|
|
|
|
Writing a new pool class
|
|
========================
|
|
|
|
If none of the pool classes supplied with the MPS are quite right for
|
|
your application, don't despair: the MPS is designed to be extensible
|
|
with new pool classes, and designed so that the properties of pools
|
|
are as orthogonal as possible. So if you need a pool containing
|
|
objects that are scannable but unformatted, or movable objects which
|
|
are manually managed, or a pool all of whose objects are roots, there
|
|
is no technical reason why it should not be possible to write it.
|
|
|
|
If you'd be interested in our developing new pool classes for your
|
|
requirements, or if you've started writing a new pool class
|
|
yourself, :ref:`we'd love to hear from you <contact>`.
|