Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-24 13:57:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

Bring html up to date.

Browse source 
Copied from Perforce
 Change: 181731
 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees 2013-05-11 20:07:28 +01:00
parent e03ccc98ac
commit eaad4493d4
78 changed files with 2746 additions and 2208 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
mps/manual/html/_downloads/scheme-advanced.c
View file

@ -4470,9 +4470,9 @@ int main(int argc, char *argv[])
/* Create an MPS arena. There is usually only one of these in a process.
It holds all the MPS "global" state and is where everything happens. */
res = mps_arena_create(&arena,
mps_arena_class_vm(),
(size_t)(32ul * 1024 * 1024));
res = mps_arena_create_k(&arena, mps_arena_class_vm(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = 32 * 1024 * 1024},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create arena");
/* Create the object format. */
@ -4488,31 +4488,29 @@ int main(int argc, char *argv[])
/* Create an Automatic Mostly-Copying (AMC) pool to manage the Scheme
objects. This is a kind of copying garbage collector. */
res = mps_pool_create(&obj_pool,
arena,
mps_class_amc(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&obj_pool, arena, mps_class_amc(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create obj pool");
/* Create an allocation point for fast in-line allocation of objects
from the `obj_pool`. You'd usually want one of these per thread
for your primary pools. This interpreter is single threaded, though,
so we just have it in a global. See topic/allocation. */
res = mps_ap_create(&obj_ap, obj_pool);
res = mps_ap_create_k(&obj_ap, obj_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create obj allocation point");
/* Create an Automatic Mostly-Copying Zero-rank (AMCZ) pool to
manage the leaf objects. */
res = mps_pool_create(&leaf_pool,
arena,
mps_class_amcz(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&leaf_pool, arena, mps_class_amcz(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create leaf pool");
/* Create allocation point for leaf objects. */
res = mps_ap_create(&leaf_ap, leaf_pool);
res = mps_ap_create_k(&leaf_ap, leaf_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create leaf objects allocation point");
/* Create the buckets format. */
@ -4521,17 +4519,21 @@ int main(int argc, char *argv[])
/* Create an Automatic Weak Linked (AWL) pool to manage the hash table
buckets. */
res = mps_pool_create(&buckets_pool,
arena,
mps_class_awl(),
buckets_fmt,
buckets_find_dependent);
res = mps_pool_create_k(&buckets_pool, arena, mps_class_awl(),
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = buckets_fmt},
{MPS_KEY_AWL_FIND_DEPENDENT,
.val.addr_method = buckets_find_dependent},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create buckets pool");
/* Create allocation points for weak and strong buckets. */
res = mps_ap_create(&strong_buckets_ap, buckets_pool, mps_rank_exact());
res = mps_ap_create_k(&strong_buckets_ap, buckets_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_exact()},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create strong buckets allocation point");
res = mps_ap_create(&weak_buckets_ap, buckets_pool, mps_rank_weak());
res = mps_ap_create_k(&weak_buckets_ap, buckets_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_weak()},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create weak buckets allocation point");
/* Register the current thread with the MPS. The MPS must sometimes

17
mps/manual/html/_downloads/scheme.c
View file

@ -4391,9 +4391,9 @@ int main(int argc, char *argv[])
/* Create an MPS arena. There is usually only one of these in a process.
It holds all the MPS "global" state and is where everything happens. */
res = mps_arena_create(&arena,
mps_arena_class_vm(),
(size_t)(32 * 1024 * 1024));
res = mps_arena_create_k(&arena, mps_arena_class_vm(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = 32 * 1024 * 1024},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create arena");
/* Create the object format. */
@ -4409,18 +4409,17 @@ int main(int argc, char *argv[])
/* Create an Automatic Mostly-Copying (AMC) pool to manage the Scheme
objects. This is a kind of copying garbage collector. */
res = mps_pool_create(&obj_pool,
arena,
mps_class_amc(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&obj_pool, arena, mps_class_amc(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create obj pool");
/* Create an allocation point for fast in-line allocation of objects
from the `obj_pool`. You'd usually want one of these per thread
for your primary pools. This interpreter is single threaded, though,
so we just have it in a global. See topic/allocation. */
res = mps_ap_create(&obj_ap, obj_pool);
res = mps_ap_create_k(&obj_ap, obj_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create obj allocation point");
/* Register the current thread with the MPS. The MPS must sometimes

695
mps/manual/html/_sources/design/cbs.txt
View file

@ -1,695 +0,0 @@
.. sources:
`<https://info.ravenbrook.com/project/mps/master/design/cbs/>`_
.. mps:prefix:: design.mps.cbs
Coalescing block structure
==========================
Introduction
------------
:mps:tag:`intro` This is the design for :mps:ref:`impl.c.cbs`, which
implements a data structure for the management of non-intersecting
memory ranges, with eager coalescence.
:mps:tag:`readership` This document is intended for any MM developer.
:mps:tag:`source` :mps:ref:`design.mps.poolmv2`, :mps:ref:`design.mps.poolmvff`.
:mps:tag:`overview` The "coalescing block structure" is a set of
addresses (or a subset of address space), with provision for efficient
management of contiguous ranges, including insertion and deletion,
high level communication with the client about the size of contiguous
ranges, and detection of protocol violations.
History
-------
:mps:tag:`hist.0` This document was derived from the outline in
:mps:ref:`design.mps.poolmv2(2)`. Written by Gavin Matthews
1998-05-01.
:mps:tag:`hist.1` Updated by Gavin Matthews 1998-07-22 in response to
approval comments in :mps:ref:`change.epcore.anchovy.160040` There is
too much fragmentation in trapping memory.
:mps:tag:`hist.2` Updated by Gavin Matthews (as part of
:mps:ref:`change.epcore.brisling.160158`: MVFF cannot be instantiated
with 4-byte alignment) to document new alignment restrictions.
:mps:tag:`hist.3` Converted from MMInfo database design document.
Richard Brooksby, 2002-06-07.
:mps:tag:`hist.4` Converted to reStructuredText. Gareth Rees,
2013-04-14.
Definitions
-----------
:mps:tag:`def.range` A (contiguous) range of addresses is a semi-open
interval on address space.
:mps:tag:`def.isolated` A contiguous range is isolated with respect to
some property it has, if adjacent elements do not have that property.
:mps:tag:`def.interesting` A block is interesting if it is of at least
the minimum interesting size specified by the client.
Requirements
------------
:mps:tag:`req.set` Must maintain a set of addresses.
:mps:tag:`req.fast` Common operations must have a low amortized cost.
:mps:tag:`req.add` Must be able to add address ranges to the set.
:mps:tag:`req.remove` Must be able to remove address ranges from the set.
:mps:tag:`req.size` Must report concisely to the client when isolated
contiguous ranges of at least a certain size appear and disappear.
:mps:tag:`req.iterate` Must support the iteration of all isolated
contiguous ranges. This will not be a common operation.
:mps:tag:`req.protocol` Must detect protocol violations.
:mps:tag:`req.debug` Must support debugging of client code.
:mps:tag:`req.small` Must have a small space overhead for the storage
of typical subsets of address space and not have abysmal overhead for
the storage of any subset of address space.
:mps:tag:`req.align` Must support an alignment (the alignment of all
addresses specifying ranges) of down to ``sizeof(void *)`` without
losing memory.
Interface
---------
:mps:tag:`header` CBS is used through :mps:ref:`impl.h.cbs`.
External types
..............
.. c:type:: typedef struct CBSStruct CBSStruct, *CBS;
:mps:tag:`type.cbs` :c:type:`CBS` is the main datastructure for
manipulating a CBS. It is intended that a :c:type:`CBSStruct` be
embedded in another structure. No convenience functions are provided
for the allocation or deallocation of the CBS.
.. c:type:: typedef struct CBSBlockStruct CBSBlockStruct, *CBSBlock;
:mps:tag:`type.cbs.block` :c:type:`CBSBlock` is the data-structure
that represents an isolated contiguous range held by the CBS. It is
returned by the new and delete methods described below.
:mps:tag:`type.cbs.method` The following methods are provided as
callbacks to advise the client of certain events. The implementation
of these functions should not cause any CBS function to be called on
the same CBS. In this respect, the CBS module is not re-entrant.
.. c:type:: typedef void (*CBSChangeSizeMethod)(CBS cbs, CBSBlock block, Size oldSize, SizeNewSize);
:mps:tag:`type.cbs.change.size.method` :c:type:`CBSChangeSizeMethod`
is the function pointer type, four instances of which are optionally
registered via CBSInit.
These callbacks are invoked under :c:func:`CBSInsert`,
:c:func:`CBSDelete`, or :c:func:`CBSSetMinSize` in certain
circumstances. Unless otherwise stated, ``oldSize`` and ``newSize``
will both be non-zero, and different. The accessors
:c:func:`CBSBlockBase`, :c:func:`CBSBlockLimit`, and
:c:func:`CBSBlockSize` may be called from within these callbacks,
except within the delete callback when ``newSize`` is zero. See
:mps:ref:`.impl.callback` for implementation details.
.. c:type:: typedef Bool (*CBSIterateMethod)(CBS cbs, CBSBlock block, void *closureP, unsigned long closureS);
:mps:tag:`type.cbs.iterate.method` :c:type:`CBSIterateMethod` is a
function pointer type for a client method invoked by the CBS module
for every isolated contiguous range in address order, when passed to
the :c:func:`CBSIterate` or :c:func:`CBSIterateLarge` functions. The
function returns a boolean indicating whether to continue with the
iteration.
External functions
..................
.. c:function:: Res CBSInit(Arena arena, CBS cbs, CBSChangeSizeMethod new, CBSChangeSizeMethod delete, CBSChangeSizeMethod grow, CBSChangeSizeMethod shrink, Size minSize, Align alignment, Bool mayUseInline)
:mps:tag:`function.cbs.init` :c:func:`CBSInit` is the function that
initialises the CBS structure. It performs allocation in the supplied
arena. Four methods are passed in as function pointers (see
:mps:ref:`.type.*` above), any of which may be ``NULL``. It receives a
minimum size, which is used when determining whether to call the
optional methods. The ``mayUseInline`` Boolean indicates whether the
CBS may use the memory in the ranges as a low-memory fallback (see
:mps:ref:`.impl.low-mem`). The alignment indicates the alignment of
ranges to be maintained. An initialised CBS contains no ranges.
:mps:tag:`function.cbs.init.may-use-inline` If ``mayUseInline`` is
set, then ``alignment`` must be at least ``sizeof(void *)``. In this
mode, the CBS will never fail to insert or delete ranges, even if
memory for control structures becomes short. Note that, in such cases,
the CBS may defer notification of new/grow events, but will report
available blocks in :c:func:`CBSFindFirst` and :c:func:`CBSFindLast`.
Such low memory conditions will be rare and transitory. See
:mps:ref:`.align` for more details.
.. c:function:: void CBSFinish(CBS cbs)
:mps:tag:`function.cbs.finish` :c:func:`CBSFinish` is the function
that finishes the CBS structure and discards any other resources
associated with the CBS.
.. c:function:: Res CBSInsert(CBS cbs, Addr base, Addr limit)
:mps:tag:`function.cbs.insert` :c:func:`CBSInsert` is the function
used to add a contiguous range specified by ``[base,limit)`` to the
CBS. If any part of the range is already in the CBS, then
:c:macro:`ResFAIL` is returned, and the CBS is unchanged. This
function may cause allocation; if this allocation fails, and any
contingency mechanism fails, then :c:macro:`ResMEMORY` is returned,
and the CBS is unchanged.
:mps:tag:`function.cbs.insert.callback` :c:func:`CBSInsert` will invoke callbacks as follows:
* ``new``: when a new block is created that is interesting. ``oldSize == 0; newSize >= minSize``.
* ``new``: when an uninteresting block coalesces to become interesting. ``0 < oldSize < minSize <= newSize``.
* ``delete``: when two interesting blocks are coalesced. ``grow`` will also be invoked in this case on the larger of the two blocks. ``newSize == 0; oldSize >= minSize``.
* ``grow``: when an interesting block grows in size. ``minSize <= oldSize < newSize``.
.. c:function:: Res CBSDelete(CBS cbs, Addr base, Addr limit)
:mps:tag:`function.cbs.delete` :c:func:`CBSDelete` is the function
used to remove a contiguous range specified by ``[base,limit)`` from
the CBS. If any part of the range is not in the CBS, then
:c:macro:`ResFAIL` is returned, and the CBS is unchanged. This
function may cause allocation; if this allocation fails, and any
contingency mechanism fails, then :c:macro:`ResMEMORY` is returned,
and the CBS is unchanged.
:mps:tag:`function.cbs.delete.callback` :c:func:`CBSDelete` will
invoke callbacks as follows:
* ``delete``: when an interesting block is entirely removed. ``newSize == 0; oldSize >= minSize``.
* ``delete``: when an interesting block becomes uninteresting. ``0 < newSize < minSize <= oldSize``.
* ``new``: when a block is split into two blocks, both of which are interesting. ``shrink`` will also be invoked in this case on the larger of the two blocks. ``oldSize == 0; newSize >= minSize``.
* ``shrink``: when an interesting block shrinks in size, but remains interesting. ``minSize <= newSize < oldSize``.
.. c:function:: void CBSIterate(CBS cbs, CBSIterateMethod iterate, void *closureP, unsigned long closureS)
:mps:tag:`function.cbs.iterate` :c:func:`CBSIterate` is the function
used to iterate all isolated contiguous ranges in a CBS. It receives a
pointer, unsigned long closure pair to pass on to the iterator method,
and an iterator method to invoke on every range in address order. If
the iterator method returns ``FALSE``, then the iteration is
terminated.
.. c:function:: void CBSIterateLarge(CBS cbs, CBSIterateMethod iterate, void *closureP, unsigned long closureS)
:mps:tag:`function.cbs.iterate.large` :c:func:`CBSIterateLarge` is the
function used to iterate all isolated contiguous ranges of size
greater than or equal to the client indicated minimum size in a CBS.
It receives a pointer, unsigned long closure pair to pass on to the
iterator method, and an iterator method to invoke on every large range
in address order. If the iterator method returns ``FALSE``, then the
iteration is terminated.
.. c:function:: void CBSSetMinSize(CBS cbs, Size minSize)
:mps:tag:`function.cbs.set.min-size` :c:func:`CBSSetMinSize` is the
function used to change the minimum size of interest in a CBS. This
minimum size is used to determine whether to invoke the client
callbacks from :c:func:`CBSInsert` and :c:func:`CBSDelete`. This
function will invoke either the ``new`` or ``delete`` callback for all
blocks that are (in the semi-open interval) between the old and new
values. ``oldSize`` and ``newSize`` will be the same in these cases.
.. c:function:: Res CBSDescribe(CBS cbs, mps_lib_FILE *stream)
:mps:tag:`function.cbs.describe` :c:func:`CBSDescribe` is a function
that prints a textual representation of the CBS to the given stream,
indicating the contiguous ranges in order, as well as the structure of
the underlying splay tree implementation. It is provided for debugging
purposes only.
.. c:function:: Addr CBSBlockBase(CBSBlock block)
:mps:tag:`function.cbs.block.base` The :c:func:`CBSBlockBase` function
returns the base of the range represented by the :c:type:`CBSBlock`.
This function may not be called from the delete callback when the
block is being deleted entirely.
.. note::
The value of the base of a particular :c:type:`CBSBlock` is not
guaranteed to remain constant across calls to :c:func:`CBSDelete`
and :c:func:`CBSInsert`, regardless of whether a callback is
invoked.
.. c:function:: Addr CBSBlockLimit(CBSBlock block)
:mps:tag:`function.cbs.block.limit` The :c:func:`CBSBlockLimit`
function returns the limit of the range represented by the
:c:type:`CBSBlock`. This function may not be called from the delete
callback when the block is being deleted entirely.
.. note::
The value of the limit of a particular :c:type:`CBSBlock` is not
guaranteed to remain constant across calls to :c:func:`CBSDelete`
and :c:func:`CBSInsert`, regardless of whether a callback is
invoked.
.. c:function:: Size CBSBlockSize(CBSBlock block)
:mps:tag:`function.cbs.block.size` The :c:func:`CBSBlockSize` function
returns the size of the range represented by the :c:type:`CBSBlock`.
This function may not be called from the ``delete`` callback when the
block is being deleted entirely.
.. note::
The value of the size of a particular :c:type:`CBSBlock` is not
guaranteed to remain constant across calls to :c:func:`CBSDelete`
and :c:func:`CBSInsert`, regardless of whether a callback is
invoked.
.. c:function:: Res CBSBlockDescribe(CBSBlock block, mps_lib_FILE *stream)
:mps:tag:`function.cbs.block.describe` The :c:func:`CBSBlockDescribe`
function prints a textual representation of the :c:type:`CBSBlock` to
the given stream. It is provided for debugging purposes only.
.. c:function:: Bool CBSFindFirst(Addr *baseReturn, Addr *limitReturn, CBS cbs, Size size, CBSFindDelete findDelete)
:mps:tag:`function.cbs.find.first` The :c:func:`CBSFindFirst` function
locates the first block (in address order) within the CBS of at least
the specified size, and returns its range. If there are no such
blocks, it returns ``FALSE``. It optionally deletes the top, bottom,
or all of the found range, depending on the ``findDelete`` argument
(this saves a separate call to :c:func:`CBSDelete`, and uses the
knowledge of exactly where we found the range), which must come from
this enumeration::
enum {
CBSFindDeleteNONE, /* don't delete after finding */
CBSFindDeleteLOW, /* delete precise size from low end */
CBSFindDeleteHIGH, /* delete precise size from high end */
CBSFindDeleteENTIRE /* delete entire range */
};
.. c:function:: Bool CBSFindLast(Addr *baseReturn, Addr *limitReturn, CBS cbs, Size size, CBSFindDelete findDelete)
:mps:tag:`function.cbs.find.last` The :c:func:`CBSFindLast` function
locates the last block (in address order) within the CBS of at least
the specified size, and returns its range. If there are no such
blocks, it returns ``FALSE``. Like :c:func:`CBSFindFirst`, it
optionally deletes the range.
.. c:function:: Bool CBSFindLargest(Addr *baseReturn, Addr *limitReturn, CBS cbs, CBSFindDelete findDelete)
:mps:tag:`function.cbs.find.largest` The :c:func:`CBSFindLargest`
function locates the largest block within the CBS, and returns its
range. If there are no blocks, it returns ``FALSE``. Like
:c:func:`CBSFindFirst`, it optionally deletes the range (specifying
``CBSFindDeleteLOW`` or ``CBSFindDeleteHIGH`` has the same effect as
``CBSFindDeleteENTIRE``).
Alignment
---------
:mps:tag:`align` When ``mayUseInline`` is specified to permit inline
data structures and hence avoid losing memory in low memory
situations, the alignments that the CBS supports are constrained by
three requirements:
- The smallest possible range (namely one that is the alignment in
size) must be large enough to contain a single ``void *`` pointer (see
:mps:ref:`.impl.low-mem.inline.grain`);
- Any larger range (namely one that is at least twice the alignment in
size) must be large enough to contain two ``void *`` pointers (see
:mps:ref:`.impl.low-mem.inline.block`);
- It must be valid on all platforms to access a ``void *`` pointer
stored at the start of an aligned range.
All alignments that meet these requirements are aligned to
``sizeof(void *)``, so we take that as the minimum alignment.
Implementation
--------------
:mps:tag:`impl` Note that this section is concerned with describing
various aspects of the implementation. It does not form part of the
interface definition.
Size change callback protocol
.............................
:mps:tag:`impl.callback` The size change callback protocol concerns
the mechanism for informing the client of the appearance and
disappearance of interesting ranges. The intention is that each range
has an identity (represented by the :c:type:`CBSBlock`). When blocks
are split, the larger fragment retains the identity. When blocks are
merged, the new block has the identity of the larger fragment.
:mps:tag:`impl.callback.delete` Consider the case when the minimum
size is ``minSize``, and :c:func:`CBSDelete` is called to remove a
range of size ``middle``. The two (possibly non-existant) neighbouring
ranges have (possibly zero) sizes ``left`` and ``right``. ``middle`` is part
of the :c:type:`CBSBlock` ``middleBlock``.
:mps:tag:`impl.callback.delete.delete` The ``delete`` callback will be
called in this case if and only if::
left + middle + right >= minSize && left < minSize && right < minSize
That is, the combined range is interesting, but neither remaining
fragment is. It will be called with the following parameters:
* ``block``: ``middleBlock``
* ``oldSize``: ``left + middle + right``
* ``newSize``: ``left >= right ? left : right``
:mps:tag:`impl.callback.delete.new` The ``new`` callback will be
called in this case if and only if::
left >= minSize && right >= minSize
That is, both remaining fragments are interesting. It will be called
with the following parameters:
* ``block``: a new block
* ``oldSize``: ``0``
* ``newSize``: ``left >= right ? right : left``
:mps:tag:`impl.callback.delete.shrink` The shrink callback will be
called in this case if and only if::
left + middle + right >= minSize && (left >= minSize || right >= minSize)
That is, at least one of the remaining fragments is still interesting. It will be called with the following parameters:
* ``block``: ``middleBlock``
* ``oldSize``: ``left + middle + right``
* ``newSize``: ``left >= right ? left : right``
:mps:tag:`impl.callback.insert` Consider the case when the minimum
size is ``minSize``, and :c:func:`CBSInsert` is called to add a range
of size ``middle``. The two (possibly non-existant) neighbouring
blocks are ``leftBlock`` and ``rightBlock``, and have (possibly zero)
sizes ``left`` and ``right``.
:mps:tag:`impl.callback.insert.delete` The ``delete`` callback will be
called in this case if and only if:
left >= minSize && right >= minSize
That is, both neighbours were interesting. It will be called with the
following parameters:
* ``block``: ``left >= right ? rightBlock : leftBlock``
* ``oldSize``: ``left >= right ? right : left``
* ``newSize``: ``0``
:mps:tag:`impl.callback.insert.new` The ``new`` callback will be
called in this case if and only if:
left + middle + right >= minSize && left < minSize && right < minSize
That is, the combined block is interesting, but neither neighbour was.
It will be called with the following parameters:
* ``block``: ``left >= right ? leftBlock : rightBlock``
* ``oldSize``: ``left >= right ? left : right``
* ``newSize``: ``left + middle + right``
:mps:tag:`impl.callback.insert.grow` The ``grow`` callback will be
called in this case if and only if::
left + middle + right >= minSize && (left >= minSize || right >= minSize)
That is, at least one of the neighbours was interesting. It will be
called with the following parameters:
* ``block``: ``left >= right ? leftBlock : rightBlock``
* ``oldSize``: ``left >= right ? left : right``
* ``newSize``: ``left + middle + right``
Splay tree
..........
:mps:tag:`impl.splay` The CBS is principally implemented using a splay
tree (see :mps:ref:`design.mps.splay`). Each splay tree node is
embedded in a CBSBlock that represents a semi-open address range. The
key passed for comparison is the base of another range.
:mps:tag:`impl.splay.fast-find` :c:func:`CBSFindFirst` and
:c:func:`CBSFindLast` use the update/refresh facility of splay trees
to store, in each :c:type:`CBSBlock`, an accurate summary of the
maximum block size in the tree rooted at the corresponding splay node.
This allows rapid location of the first or last suitable block, and
very rapid failure if there is no suitable block.
:mps:tag:`impl.find-largest` :c:func:`CBSFindLargest` simply finds out
the size of the largest block in the CBS from the root of the tree
(using :c:func:`SplayRoot`), and does :c:func:`SplayFindFirst` for a
block of that size. This is O(log(*n*)) in the size of the free list,
so it's about the best you can do without maintaining a separate
priority queue, just to do :c:func:`CBSFindLargest`. Except when the
emergency lists (see :mps:ref:`.impl.low-mem`) are in use, they are
also searched.
Low memory behaviour
....................
:mps:tag:`impl.low-mem` Low memory situations cause problems when the
CBS tries to allocate a new :c:type:`CBSBlock` structure for a new
isolated range as a result of either :c:func:`CBSInsert` or
:c:func:`CBSDelete`, and there is insufficient memory to allocation
the :c:type:`CBSBlock` structure:
:mps:tag:`impl.low-mem.no-inline` If ``mayUseInline`` is ``FALSE``,
then the range is not added to the CBS, and the call to
:c:func:`CBSInsert` or :c:func:`CBSDelete` returns ``ResMEMORY``.
:mps:tag:`impl.low-mem.inline` If ``mayUseInline`` is ``TRUE``:
:mps:tag:`impl.low-mem.inline.block` If the range is large enough to
contain an inline block descriptor consisting of two pointers, then it
is kept on an emergency block list. The CBS will eagerly attempt to
add this block back into the splay tree during subsequent calls to
:c:func:`CBSInsert` and :c:func:`CBSDelete`. The CBS will also keep
its emergency block list in address order, and will coalesce this list
eagerly. Some performance degradation will be seen when the emergency
block list is in use. Ranges on this emergency block list will not be
made available to the CBS's client via callbacks. :c:func:`CBSIterate`
and :c:func:`CBSIterateLarge` will not iterate over ranges on this
list.
:mps:tag:`impl.low-mem.inline.block.structure` The two pointers stored
are to the next such block (or ``NULL``), and to the limit of the
block, in that order.
:mps:tag:`impl.low-mem.inline.grain` Otherwise, the range must be
large enough to contain an inline grain descriptor consisting of one
pointer, then it is kept on an emergency grain list. The CBS will
eagerly attempt to add this grain back into either the splay tree or
the emergency block list during subsequent calls to
:c:func:`CBSInsert` and :c:func:`CBSDelete`. The CBS will also keep
its emergency grain list in address order. Some performance
degradation will be seen when the emergency grain list is in use.
Ranges on this emergency grain list will not be made available to the
CBS's client via callbacks. :c:func:`CBSIterate` and
:c:func:`CBSIterateLarge` will not iterate over ranges on this list.
:mps:tag:`impl.low-mem.inline.grain.structure` The pointer stored is
to the next such grain, or ``NULL``.
The CBS block
.............
:mps:tag:`impl.cbs.block` The block contains a base-limit pair and a
splay tree node.
:mps:tag:`impl.cbs.block.special` The base and limit may be equal if
the block is halfway through being deleted.
:mps:tag:`impl.cbs.block.special.just` This conflates values and
status, but is justified because block size is very important.
Testing
-------
:mps:tag:`test` The following testing will be performed on this module:
:mps:tag:`test.cbstest` There is a stress test for this module in
:mps:ref:`impl.c.cbstest`. This allocates a large block of memory and
then simulates the allocation and deallocation of ranges within this
block using both a :c:type:`CBS` and a :c:type:`BT`. It makes both
valid and invalid requests, and compares the :c:type:`CBS` response to
the correct behaviour as determined by the :c:type:`BT`. It also
iterates the ranges in the :c:type:`CBS`, comparing them to the
:c:type:`BT`. It also invokes the :c:func:`CBSDescribe` method, but
makes no automatic test of the resulting output. It does not currently
test the callbacks.
:mps:tag:`test.pool` Several pools (currently :ref:`pool-mvt` and
:ref:`pool-mvff`) are implemented on top of a CBS. These pool are
subject to testing in development, QA, and are/will be heavily
exercised by customers.
Notes for future development
----------------------------
:mps:tag:`future.not-splay` The initial implementation of CBSs is
based on splay trees. It could be revised to use any other data
structure that meets the requirements (especially
:mps:ref:`.req.fast`).
:mps:tag:`future.hybrid` It would be possible to attenuate the problem
of :mps:ref:`.risk.overhead` (below) by using a single word bit set to
represent the membership in a (possibly aligned) word-width of grains.
This might be used for block sizes less than a word-width of grains,
converting them when they reach all free in the bit set. Note that
this would make coalescence slightly less eager, by up to
``(word-width - 1)``.
Risks
-----
:mps:tag:`risk.overhead` Clients should note that the current
implementation of CBSs has a space overhead proportional to the number
of isolated contiguous ranges. [Four words per range.] If the CBS
contains every other grain in an area, then the overhead will be large
compared to the size of that area. [Four words per two grains.] See
:mps:ref:`.future.hybrid` for a suggestion to solve this problem. An
alternative solution is to use CBSs only for managing long ranges.
Proposed hybrid implementation
------------------------------
.. note::
The following relates to a pending re-design and does not yet
relate to any working source version. GavinM 1998-09-25
The CBS system provides its services by combining the services
provided by three subsidiary CBS modules:
- ``CBSST`` -- Splay Tree: Based on out-of-line splay trees; must
allocate to insert isolated, which may therefore fail.
- ``CBSBL`` -- Block List: Based on a singly-linked list of variable
sized ranges with inline descriptors; ranges must be at least large
enough to store the inline descriptor.
- ``CBSGL`` -- Grain List: Based on a singly-linked list of fixed size
ranges with inline descriptors; the ranges must be the alignment of
the CBS.
The three sub-modules have a lot in common. Although their methods are
not invoked via a dispatcher, they have been given consistent
interfaces, and consistent internal appearance, to aid maintenance.
Methods supported by sub-modules (not all sub-modules support all
methods):
- ``MergeRange`` -- Finds any ranges in the specific CBS adjacent to
the supplied one. If there are any, it extends the ranges, possibly
deleting one of them. This cannot fail, but should return ``FALSE``
if there is an intersection between the supplied range and a range
in the specific CBS.
- ``InsertIsolatedRange`` -- Adds a range to the specific CBS that is
not adjacent to any range already in there. Depending on the
specific CBS, this may be able to fail for allocation reasons, in
which case it should return ``FALSE``. It should :c:func:`AVER` if
the range is adjacent to or intersects with a range already there.
- ``RemoveAdjacentRanges`` -- Finds and removes from the specific CBS
any ranges that are adjacent to the supplied range. Should return
``FALSE`` if the supplied range intersects with any ranges already
there.
- ``DeleteRange`` -- Finds and deletes the supplied range from the
specific CBS. Returns a tri-state result:
- ``Success`` -- The range was successfully deleted. This may have
involved the creation of a new range, which should be done via
``CBSInsertIsolatedRange``.
- ``ProtocolError`` -- Either some non-trivial strict subset of the
supplied range was in the specific CBS, or a range adjacent to the
supplied range was in the specific CBS. Either of these indicates
a protocol error.
- ``NoIntersection`` -- The supplied range was not found in the CBS.
This may or not be a protocol error, depending on the invocation
context.
- ``FindFirst`` -- Returns the first (in address order) range in the
specific CBS that is at least as large as the supplied size, or
``FALSE`` if there is no such range.
- ``FindFirstBefore`` -- As ``FindFirst``, but only finds ranges prior
to the supplied address.
- ``FindLast`` -- As ``FindFirst``, but finds the last such range in
address order.
- ``FindLastAfter`` -- ``FindLast`` equivalent of ``FindFirstBefore``.
- ``Init`` -- Initialise the control structure embedded in the CBS.
- ``Finish`` -- Finish the control structure embedded in the CBS.
- ``InlineDescriptorSize`` -- Returns the aligned size of the inline descriptor.
- ``Check`` -- Checks the control structure embedded in the CBS.
The CBS supplies the following utilities:
- ``CBSAlignment`` -- Returns the alignment of the CBS.
- ``CBSMayUseInline`` -- Returns whether the CBS may use the memory in
the ranges stored.
- ``CBSInsertIsolatedRange`` -- Wrapper for ``CBS*InsertIsolatedRange``.
Internally, the ``CBS*`` sub-modules each have an internal structure
``CBS*Block`` that represents an isolated range within the module. It
supports the following methods (for sub-module internal use):
- ``BlockBase`` -- Returns the base of the associated range;
- ``BlockLimit``
- ``BlockRange``
- ``BlockSize``

106
mps/manual/html/_sources/design/check.txt
View file

@ -1,106 +0,0 @@
.. sources:
`<https://info.ravenbrook.com/project/mps/master/design/check/>`_
.. mps:prefix:: design.mps.check
Checking
========
Introduction
------------
This documents the design of structure checking within the MPS.
History
-------
:mps:tag:`hist.0` Incomplete design. Gavin Matthews, 1996-08-05.
:mps:tag:`hist.1` Converted from MMInfo database design document.
Richard Brooksby, 2002-06-07.
:mps:tag:`hist.2` Converted to reStructuredText. Gareth Rees,
2013-03-12.
Implementation
--------------
:mps:tag:`level` There are three levels of checking:
1. :mps:tag:`level.sig` The lowest level checks only that the
structure has a valid :c:type:`Signature` (see
:mps:ref:`design.mps.sig`).
2. :mps:tag:`level.shallow` Shallow checking checks all local fields
(including signature) and also checks the signatures of any parent
or child structures.
3. :mps:tag:`level.deep` Deep checking checks all local fields
(including signatures), the signatures of any parent structures,
and does full recursive checking on any child structures.
:mps:tag:`level.control` Control over the levels of checking is via
the definition of at most one of the macros
:c:macro:`TARGET_CHECK_SHALLOW` (which if defined gives
:mps:ref:`.level.shallow`), :c:macro:`TARGET_CHECK_DEEP` (which if
defined gives :mps:ref:`.level.deep`). If neither macro is defined
then :mps:ref:`.level.sig` is used. These macros are not intended to
be manipulated directly by developers, they should use the interface
in :mps:ref:`impl.h.target`.
:mps:tag:`order` Because deep checking (:mps:ref:`.level.deep`) uses
unchecked recursion, it is important that child relationships are
acyclic (:mps:ref:`.macro.down`).
:mps:tag:`fun` Every abstract data type which is a structure pointer
should have a function ``<type>Check`` which takes a pointer of type
``<type>`` and returns a :c:type:`Bool`. It should check all fields in
order, using one of the macros in :mps:ref:`.macro`, or document why
not.
:mps:tag:`fun.omit` The only fields which should be omitted from a
check function are those for which there is no meaningful check (for
example, an unlimited unsigned integer with no relation to other fields).
:mps:tag:`fun.return` Although the function returns a :c:type:`Bool`,
if the assert handler returns (or there is no assert handler), then
this is taken to mean "ignore and continue", and the check function
hence returns ``TRUE``.
:mps:tag:`macro` Checking is implemented by invoking four macros in :mps:ref:`impl.h.assert`:
* :mps:tag:`macro.sig` ``CHECKS(type, val)`` checks the signature
only, and should be called precisely on ``type`` and the received
object pointer.
* :mps:tag:`macro.local` ``CHECKL(cond)`` checks a local field
(depending on level; see :mps:ref:`.level`), and should be called on
each local field that is not an abstract data type structure pointer
itself (apart from the signature), with an appropriate normally-true
test condition.
* :mps:tag:`macro.up` ``CHECKU(type, val)`` checks a parent abstract
data type structure pointer, performing at most signature checks
(depending on level; see :mps:ref:`.level`). It should be called
with the parent type and pointer.
* :mps:tag:`macro.down` ``CHECKD(type, val)`` checks a child abstract
data type structure pointer, possibly invoking ``<type>Check``
(depending on level; see :mps:ref:`.level`). It should be called
with the child type and pointer.
:mps:tag:`full-type` ``CHECKS``, ``CHECKD``, ``CHECKU``, all operate
only on fully fledged types. This means the type has to provide a
function ``Bool TypeCheck(Type type)`` where ``Type`` is substituted
for the name of the type (for example, :c:func:`PoolCheck`), and the
expression ``obj->sig`` must be a valid value of type :c:type:`Sig`
whenever ``obj`` is a valid value of type ``Type``.
:mps:tag:`type.no-sig` This tag is to be referenced in implementations
whenever the form ``CHECKL(ThingCheck(thing))`` is used instead of
``CHECK{U,D}(Thing, thing)`` because ``Thing`` is not a fully fledged
type (:mps:ref:`.full-type`).

33
mps/manual/html/_sources/glossary/c.txt
View file

@ -8,6 +8,39 @@ Memory Management Glossary: C
.. glossary::
C89
.. see:: :term:`C90`.
C90
.. aka:: *C89*.
A revision of the ANSI/ISO Standard for the :term:`C`
programming language. Although more than twenty years old, it
remains the only form of Standard C that is supported by all
the major compilers, including Microsoft Visual C.
.. mps:specific::
The public interface conforms to this standard. See
:ref:`topic-interface`.
.. bibref:: :ref:`ISO/IEC 9899:1990 <C1990>`.
C99
A revision of the ANSI/ISO Standard for C the :term:`C`
programming language.
.. mps:specific::
:term:`Keyword arguments` can be conveniently passed to
functions using C99's compound literal syntax. See
:ref:`topic-keyword`.
.. bibref:: :ref:`ISO/IEC 9899:1999 <C1999>`.
cache (1)
.. aka:: *memory cache*, *cache memory*.

11
mps/manual/html/_sources/glossary/k.txt
View file

@ -12,6 +12,17 @@ Memory Management Glossary: K
.. see:: :term:`kilobyte`.
keyword argument
An optional argument to a function call, identified by an
associated keyword.
.. mps:specific::
Keyword arguments are passed to functions in the MPS
interface as arrays of structures of type
:c:type:`mps_arg_s`. See :ref:`topic-keyword`.
kilobyte
.. aka:: *kB*.

29
mps/manual/html/_sources/guide/advanced.txt
View file

@ -712,17 +712,21 @@ Finally, we can create the buckets pool and its allocation points::
/* Create an Automatic Weak Linked (AWL) pool to manage the hash table
buckets. */
res = mps_pool_create(&buckets_pool,
arena,
mps_class_awl(),
buckets_fmt,
buckets_find_dependent);
res = mps_pool_create_k(&buckets_pool, arena, mps_class_awl(),
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = buckets_fmt},
{MPS_KEY_AWL_FIND_DEPENDENT,
.val.addr_method = buckets_find_dependent},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create buckets pool");
/* Create allocation points for weak and strong buckets. */
res = mps_ap_create(&strong_buckets_ap, buckets_pool, mps_rank_exact());
res = mps_ap_create_k(&strong_buckets_ap, buckets_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_exact()},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create strong buckets allocation point");
res = mps_ap_create(&weak_buckets_ap, buckets_pool, mps_rank_weak());
res = mps_ap_create_k(&weak_buckets_ap, buckets_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_weak()},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create weak buckets allocation point");
By adding the line::
@ -888,15 +892,14 @@ Second, the leaf objects must be allocated on ``leaf_ap`` instead of
/* Create an Automatic Mostly-Copying Zero-rank (AMCZ) pool to
manage the leaf objects. */
res = mps_pool_create(&leaf_pool,
arena,
mps_class_amcz(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&leaf_pool, arena, mps_class_amcz(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create leaf pool");
/* Create allocation point for leaf objects. */
res = mps_ap_create(&leaf_ap, leaf_pool);
res = mps_ap_create_k(&leaf_ap, leaf_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create leaf objects allocation point");
Note that the new pool shared a :term:`generation chain` with the old

41
mps/manual/html/_sources/guide/lang.txt
View file

@ -155,24 +155,32 @@ rather than having to pass it around everywhere::
static mps_arena_t arena;
Create an arena by calling :c:func:`mps_arena_create`. This function
takes a third argument when creating a virtual memory arena: the size of
the amount of virtual virtual :term:`address space` (*not* :term:`RAM`),
in bytes, that the arena will reserve initially. The MPS will ask for
Create an arena by calling :c:func:`mps_arena_create_k`. This function
takes a :term:`keyword argument` when creating a virtual memory arena:
the size of virtual :term:`address space` (*not* :term:`RAM`), in
bytes, that the arena will reserve initially. The MPS will ask for
more address space if it runs out, but the more times it has to extend
its address space, the less efficient garbage collection will become.
The MPS works best if you reserve an address space that is several times
larger than your peak memory usage.
The MPS works best if you reserve an address space that is several
times larger than your peak memory usage.
.. note::
Functions in the MPS interface take :term:`keyword arguments` for
arguments that are optional, or are only required in some
circumstances. These argument are passed in the form of an array
of structures of type :c:type:`mps_arg_s`. See
:ref:`topic-keyword` for the full details.
Let's reserve 32 megabytes::
mps_res_t res;
res = mps_arena_create(&arena,
mps_arena_class_vm(),
(size_t)(32 * 1024 * 1024));
res = mps_arena_create_k(&arena, mps_arena_class_vm(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = 32 * 1024 * 1024},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create arena");
:c:func:`mps_arena_create` is typical of functions in the MPS
:c:func:`mps_arena_create_k` is typical of functions in the MPS
interface in that it stores its result in a location pointed to by an
:term:`out parameter` (here, ``&arena``) and returns a :term:`result
code`, which is :c:macro:`MPS_RES_OK` if the function succeeded, or
@ -762,11 +770,10 @@ Third, the :term:`generation chain`::
And finally the :term:`pool`::
mps_pool_t obj_pool;
res = mps_pool_create(&obj_pool,
arena,
mps_class_amc(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&obj_pool, arena, mps_class_amc(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create obj pool");
@ -1080,13 +1087,13 @@ may abort.
The MPS solves this problem via the fast, nearly lock-free
:ref:`topic-allocation-point-protocol`. This needs an additional
structure, an :term:`allocation point`, to be attached to the pool by
calling :c:func:`mps_ap_create`::
calling :c:func:`mps_ap_create_k`::
static mps_ap_t obj_ap;
/* ... */
res = mps_ap_create(&obj_ap, obj_pool, mps_rank_exact());
res = mps_ap_create_k(&obj_ap, obj_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create obj allocation point");
And then the constructor can be implemented like this::

8
mps/manual/html/_sources/mmref/bib.txt
View file

@ -215,6 +215,14 @@ Bibliography
Richard Brooksby. 2002. "`The Memory Pool System: Thirty person-years of memory management development goes Open Source <http://www.ravenbrook.com/project/mps/doc/2002-01-30/ismm2002-paper/>`_". ISMM'02.
* .. _C1990:
International Standard ISO/IEC 9899:1990. "Programming languages — C".
* .. _C1999:
International Standard ISO/IEC 9899:1999. "`Programming languages — C <http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf>`_".
* .. _CGZ94:
Brad Calder, Dirk Grunwald, Benjamin Zorn. 1994. "`Quantifying Behavioral Differences Between C and C++ Programs <http://cseclassic.ucsd.edu/users/calder/papers/JplVersion.pdf>`_". *Journal of Programming Languages.* 2(4):313--351.

2
mps/manual/html/_sources/mmref/lang.txt
View file

@ -82,7 +82,7 @@ Memory management in various languages
.. seealso:: :term:`automatic storage duration`, :term:`static storage duration`.
.. bibref:: :ref:`Boehm & Weiser (1988) <BW88>`, :ref:`Daconta (1993) <DACONTA93>`, :ref:`Zorn (1993) <ZORN93>`.
.. bibref:: :ref:`ISO/IEC 9899:1990 <C1990>`, :ref:`ISO/IEC 9899:1999 <C1999>`, :ref:`Boehm & Weiser (1988) <BW88>`, :ref:`Daconta (1993) <DACONTA93>`, :ref:`Zorn (1993) <ZORN93>`.
.. link::

38
mps/manual/html/_sources/pool/amc.txt
View file

@ -100,20 +100,36 @@ AMC interface
Return the :term:`pool class` for an AMC (Automatic
Mostly-Copying) :term:`pool`.
When creating an AMC pool, :c:func:`mps_pool_create` takes two
extra arguments::
When creating an AMC pool, :c:func:`mps_pool_create_k` requires
two :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_amc(),
mps_fmt_t fmt,
mps_chain_t chain)
* :c:macro:`MPS_KEY_FORMAT` (member ``.val.format``; type
:c:type:`mps_fmt_t`) specifies the :term:`object format` for the
objects allocated in the pool. The format must provide a
:term:`scan method`, a :term:`skip method`, a :term:`forward
method`, an :term:`is-forwarded method` and a :term:`padding
method`.
``fmt`` specifies the :term:`object format` for the objects
allocated in the pool. The format must provide a :term:`scan
method`, a :term:`skip method`, a :term:`forward method`, an
:term:`is-forwarded method` and a :term:`padding method`.
* :c:macro:`MPS_KEY_CHAIN` (member ``.val.chain``; type
:c:type:`mps_chain_t`) specifies the :term:`generation chain`
for the pool.
``chain`` specifies the :term:`generation chain` for the pool.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_amc(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = chain},
{MPS_KEY_FORMAT, .val.format = fmt},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the format and
chain like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_amc(),
mps_fmt_t fmt,
mps_chain_t chain)
.. index::

37
mps/manual/html/_sources/pool/amcz.txt
View file

@ -59,17 +59,32 @@ AMCZ interface
Return the :term:`pool class` for an AMCZ (Automatic
Mostly-Copying Zero-rank) :term:`pool`.
When creating an AMCZ pool, :c:func:`mps_pool_create` takes two
extra arguments::
When creating an AMCZ pool, :c:func:`mps_pool_create_k` requires
two :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_amcz(),
mps_fmt_t fmt,
mps_chain_t chain)
* :c:macro:`MPS_KEY_FORMAT` (member ``.val.format``; type
:c:type:`mps_fmt_t`) specifies the :term:`object format` for the
objects allocated in the pool. The format must provide a
:term:`skip method`, a :term:`forward method`, an
:term:`is-forwarded method` and a :term:`padding method`.
``fmt`` specifies the :term:`object format` for the objects
allocated in the pool. The format must provide a :term:`skip
method`, a :term:`forward method`, an :term:`is-forwarded method`
and a :term:`padding method`.
* :c:macro:`MPS_KEY_CHAIN` (member ``.val.chain``; type
:c:type:`mps_chain_t`) specifies the :term:`generation chain`
for the pool.
``chain`` specifies the :term:`generation chain` for the pool.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_amcz(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = chain},
{MPS_KEY_FORMAT, .val.format = fmt},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the format and
chain like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_amcz(),
mps_fmt_t fmt,
mps_chain_t chain)

59
mps/manual/html/_sources/pool/ams.txt
View file

@ -103,20 +103,34 @@ AMS interface
Return the :term:`pool class` for an AMS (Automatic Mark & Sweep)
:term:`pool`.
When creating an AMS pool, :c:func:`mps_pool_create` takes two
extra arguments::
When creating an AMS pool, :c:func:`mps_pool_create_k` requires
two :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_ams(),
mps_fmt_t fmt,
mps_chain_t chain)
* :c:macro:`MPS_KEY_FORMAT` (member ``.val.format``; type
:c:type:`mps_fmt_t`) specifies the :term:`object format` for the
objects allocated in the pool. The format must provide a
:term:`scan method` and a :term:`skip method`.
``fmt`` specifies the :term:`object format` for the objects
allocated in the pool. The format must provide a :term:`scan
method` and a :term:`skip method`.
* :c:macro:`MPS_KEY_CHAIN` (member ``.val.chain``; type
:c:type:`mps_chain_t`) specifies the :term:`generation chain`
for the pool. It must have a single generation.
``chain`` specifies the :term:`generation chain` for the pool. It
must have a single generation.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_ams(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = chain},
{MPS_KEY_FORMAT, .val.format = fmt},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the format and
chain like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_ams(),
mps_fmt_t fmt,
mps_chain_t chain)
.. c:function:: mps_class_t mps_class_ams_debug(void)
@ -124,16 +138,19 @@ AMS interface
A :ref:`debugging <topic-debugging>` version of the AMS pool
class.
When creating a debugging AMS pool, :c:func:`mps_pool_create`
takes three extra arguments::
When creating a debugging AMS pool, :c:func:`mps_pool_create_k`
requires three keyword arguments: :c:macro:`MPS_KEY_FORMAT` and
:c:macro:`MPS_KEY_CHAIN` are as described above, and
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` specifies the debugging
options. See :c:type:`mps_debug_option_s`.
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_ams_debug(),
mps_debug_option_s debug_option,
mps_fmt_t fmt,
mps_chain_t chain)
.. deprecated:: starting with version 1.112.
``debug_option`` specifies the debugging options. See
:c:type:`mps_debug_option_s`.
When using :c:func:`mps_pool_create`, pass the format,
chain, and debugging options like this::
``fmt`` and ``chain`` are the same as for :c:func:`mps_class_ams`.
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_ams_debug(),
mps_debug_option_s debug_option,
mps_fmt_t fmt,
mps_chain_t chain)

69
mps/manual/html/_sources/pool/awl.txt
View file

@ -318,34 +318,59 @@ AWL interface
Return the :term:`pool class` for an AWL (Automatic Weak Linked)
:term:`pool`.
When creating an AWL pool, :c:func:`mps_pool_create` takes two
extra arguments::
When creating an AWL pool, :c:func:`mps_pool_create_k` requires
two :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_awl(),
mps_fmt_t fmt,
mps_awl_find_dependent_t find_dependent)
* :c:macro:`MPS_KEY_FORMAT` (member ``.val.format``; type
:c:type:`mps_fmt_t`) specifies the :term:`object format` for the
objects allocated in the pool. The format must provide a :term:`scan
method` and a :term:`skip method`.
``fmt`` specifies the :term:`object format` for the objects
allocated in the pool. The format must provide a :term:`scan
method` and a :term:`skip method`.
* :c:macro:`MPS_KEY_AWL_FIND_DEPENDENT` (member
``.val.addr_method``; type :c:type:`mps_awl_find_dependent_t`)
is a function that specifies how to find the :term:`dependent
object` for an object in the pool.
``find_dependent`` is a function of type
:c:type:`mps_awl_find_dependent_t` that specifies how to find the
:term:`dependent object` for an object in the pool.
For example, in :term:`C99`::
When creating an allocation point on an AWL pool,
:c:func:`mps_ap_create` takes one extra argument::
res = mps_pool_create_k(&pool, arena, mps_class_awl(),
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = fmt},
{MPS_KEY_AWL_FIND_DEPENDENT, .val.addr_method = find_dependent},
{MPS_KEY_ARGS_END}});
mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool,
mps_rank_t rank)
.. deprecated:: starting with version 1.112.
``rank`` specifies the :term:`rank` of references in objects
allocated on this allocation point. It must be
:c:func:`mps_rank_exact` (if the objects allocated on this
allocation point will contain :term:`exact references`), or
:c:func:`mps_rank_weak` (if the objects will contain :term:`weak
references (1)`).
When using :c:func:`mps_pool_create`, pass the format and
find-dependent function like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_awl(),
mps_fmt_t fmt,
mps_awl_find_dependent_t find_dependent)
When creating an :term:`allocation point` on an AWL pool,
:c:func:`mps_ap_create_k` requires one keyword argument:
* :c:macro:`MPS_KEY_RANK` (member ``.val.rank``; type
:c:type:`mps_rank_t`) specifies the :term:`rank` of references
in objects allocated on this allocation point. It must be
:c:func:`mps_rank_exact` (if the objects allocated on this
allocation point will contain :term:`exact references`), or
:c:func:`mps_rank_weak` (if the objects will contain :term:`weak
references (1)`).
For example, in :term:`C99`::
res = mps_ap_create_k(&ap, awl_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_weak()},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_ap_create`, pass the rank like this::
mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool,
mps_rank_t rank)
.. c:type:: mps_addr_t (*mps_awl_find_dependent_t)(mps_addr_t addr)

28
mps/manual/html/_sources/pool/lo.txt
View file

@ -105,13 +105,25 @@ LO interface
Return the :term:`pool class` for an LO (Leaf Object)
:term:`pool`.
When creating an LO pool, :c:func:`mps_pool_create` takes one
extra argument::
When creating an LO pool, :c:func:`mps_pool_create_k` require one
:term:`keyword argument`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_lo(),
mps_fmt_t fmt)
* :c:macro:`MPS_KEY_FORMAT` (member ``.val.format``; type
:c:type:`mps_fmt_t`) specifies the :term:`object format` for the
objects allocated in the pool. The format must provide a :term:`skip
method`.
``fmt`` specifies the :term:`object format` for the objects
allocated in the pool. The format must provide a :term:`skip
method`.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_lo(),
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = fmt},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the format like
this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_lo(),
mps_fmt_t fmt)

42
mps/manual/html/_sources/pool/mfs.txt
View file

@ -77,19 +77,35 @@ MFS interface
Return the :term:`pool class` for an MFS (Manual Fixed Small)
:term:`pool`.
When creating an MFS pool, :c:func:`mps_pool_create` takes two
extra arguments::
When creating an MFS pool, :c:func:`mps_pool_create_k` requires
two :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mfs(),
mps_size_t extend_size,
mps_size_t unit_size)
* :c:macro:`MPS_KEY_MFS_UNIT_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the :term:`size` of blocks that will be
allocated from this pool, in :term:`bytes (1)`. It must be at
least one :term:`word`.
``extend_size`` is the :term:`size` of segment that the pool will
request from the :term:`arena`. It must be at least as big as
``unit_size``. If this is not a multiple of ``unit_size``, there
will be wasted space in each segment.
* :c:macro:`MPS_KEY_EXTEND_BY` (member ``.val.size``; type
:c:type:`size_t`) is the :term:`size` of segment that the pool
will request from the :term:`arena`. It must be at least as big
as the unit size specified by the
:c:macro:`MPS_KEY_MFS_UNIT_SIZE` keyword argument. If this is
not a multiple of the unit size, there will be wasted space in
each segment.
``unit_size`` is the :term:`size` of blocks that will be allocated
from this pool, in :term:`bytes (1)`. It must be at least one
:term:`word`.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_mfs(),
(mps_arg_s[]){{MPS_KEY_MFS_UNIT_SIZE, .val.size = 1024},
{MPS_KEY_EXTEND_BY, .val.size = 1024 * 1024},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the segment size and
unit size like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mfs(),
mps_size_t extend_size,
mps_size_t unit_size)

72
mps/manual/html/_sources/pool/mv.txt
View file

@ -72,22 +72,42 @@ MV interface
Return the :term:`pool class` for an MV (Manual Variable)
:term:`pool`.
When creating an MV pool, :c:func:`mps_pool_create` takes three
extra arguments::
When creating an MV pool, :c:func:`mps_pool_create_k` requires
three :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mv(),
mps_size_t extend_size,
mps_size_t average_size,
mps_size_t maximum_size)
* :c:macro:`MPS_KEY_EXTEND_BY` (member ``.val.size``; type
:c:type:`size_t`) is the :term:`size` of segment that the pool
will request from the :term:`arena`.
``extend_size`` is the :term:`size` of segment that the pool will
request from the :term:`arena`.
* :c:macro:`MPS_KEY_MEAN_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the predicted mean size of blocks that
will be allocated from the pool.
``average_size`` and ``maximum size`` are the predicted average
and maximum size of blocks that will be allocated from the pool.
These are hints to the MPS: the pool will be less efficient if
these are wrong.
* :c:macro:`MPS_KEY_MAX_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the predicted maximum size of blocks that
will be allocated from the pool.
The mean and maximum sizes are *hints* to the MPS: the pool will be
less efficient if these are wrong, but nothing will break.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_mfs(),
(mps_arg_s[]){{MPS_KEY_MEAN_SIZE, .val.size = 32},
{MPS_KEY_MAX_SIZE, .val.size = 1024},
{MPS_KEY_EXTEND_BY, .val.size = 1024 * 1024},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the segment size,
mean size, and maximum size like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mv(),
mps_size_t extend_size,
mps_size_t average_size,
mps_size_t maximum_size)
.. c:function:: mps_class_t mps_class_mv_debug(void)
@ -95,21 +115,23 @@ MV interface
A :ref:`debugging <topic-debugging>` version of the MV pool
class.
When creating a debugging MV pool, :c:func:`mps_pool_create`
takes four extra arguments::
When creating a debugging MV pool, :c:func:`mps_pool_create_k`
requires four keyword arguments: :c:macro:`MPS_KEY_EXTEND_SIZE`,
:c:macro:`MPS_KEY_MEAN_SIZE`, :c:macro:`MPS_KEY_MAX_SIZE` are as
described above, and :c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS`
specifies the debugging options. See :c:type:`mps_debug_option_s`.
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mv_debug(),
mps_debug_option_s debug_option,
mps_size_t extend_size,
mps_size_t average_size,
mps_size_t maximum_size)
.. deprecated:: starting with version 1.112.
``debug_option`` specifies the debugging options. See
:c:type:`mps_debug_option_s`.
When using :c:func:`mps_pool_create`, pass the debugging
options, segment size, mean size, and maximum size like this::
``extend_size``, ``average_size`` and ``maximum_size`` are as
documented in :c:func:`mps_class_mv`.
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mv_debug(),
mps_debug_option_s debug_option,
mps_size_t extend_size,
mps_size_t average_size,
mps_size_t maximum_size)
.. index::

108
mps/manual/html/_sources/pool/mvff.txt
View file

@ -112,37 +112,62 @@ MVFF interface
Return the :term:`pool class` for an MVFF (Manual Variable First
Fit) :term:`pool`.
When creating an MVFF pool, :c:func:`mps_pool_create` takes six
extra arguments::
When creating an MVFF pool, :c:func:`mps_pool_create_k` requires
six :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mvff(),
mps_size_t extend_size,
mps_size_t average_size,
mps_align_t alignment,
mps_bool_t slot_high,
mps_bool_t arena_high,
mps_bool_t first_fit)
* :c:macro:`MPS_KEY_EXTEND_BY` (member ``.val.size``; type
:c:type:`size_t`) is the :term:`size` of segment that the pool
will request from the :term:`arena`.
``extend_size`` is the :term:`size` of segment that the pool will
request from the :term:`arena`.
* :c:macro:`MPS_KEY_MEAN_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the predicted mean size of blocks that will
be allocated from the pool. This is a *hint* to the MPS: the
pool will be less efficient if this is wrong, but nothing will
break.
``average_size`` is the predicted average size of blocks that will
be allocated from the pool.
* :c:macro:`MPS_KEY_ALIGN` (member ``.val.align``; type
:c:type:`mps_align_t`) is the :term:`alignment` of addresses for
allocation (and freeing) in the pool. If an unaligned size is
passed to :c:func:`mps_alloc` or :c:func:`mps_free`, it will be
rounded up to the pool's alignment. The minimum alignment
supported by pools of this class is ``sizeof(void *)``.
``alignment`` is the :term:`alignment` of addresses for allocation
(and freeing) in the pool. If an unaligned size is passed to
:c:func:`mps_alloc` or :c:func:`mps_free`, it will be rounded up
to the pool's alignment. The minimum alignment supported by pools
of this class is ``sizeof(void *)``.
* :c:macro:`MPS_KEY_MVFF_ARENA_HIGH` (member ``.val.b``; type
:c:type:`mps_bool_t`) indicates whether new segments for
buffered allocation are acquired at high addresses (if true), or
at low addresses (if false).
``slot_high`` is undocumented. It must have the same value as
``arena_high``.
* :c:macro:`MPS_KEY_MVFF_SLOT_HIGH` (member ``.val.b``; type
:c:type:`mps_bool_t`) is undocumented. It must have the same
value as :c:macro:`MPS_KEY_MVFF_ARENA_HIGH`.
If ``arena_high`` is true, new segments for buffered allocation
are acquired at high addresses; if false, at low addresses.
* :c:macro:`MPS_KEY_MVFF_FIRST_FIT` (member ``.val.b``; type
:c:type:`mps_bool_t`) is undocumented and must be set to true.
``first_fit`` is undocumented and must be set to true.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_mvff(),
(mps_arg_s[]){{MPS_KEY_EXTEND_BY, .val.size = },
{MPS_KEY_MEAN_SIZE, .val.size = },
{MPS_KEY_ALIGN, .val.align = },
{MPS_KEY_MVFF_ARENA_HIGH, .val.b = 0},
{MPS_KEY_MVFF_SLOT_HIGH, .val.b = 0},
{MPS_KEY_MVFF_FIRST_FIT, .val.b = 1},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the arguments like
this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mvff(),
mps_size_t extend_size,
mps_size_t average_size,
mps_align_t alignment,
mps_bool_t slot_high,
mps_bool_t arena_high,
mps_bool_t first_fit)
.. c:function:: mps_class_t mps_class_mvff_debug(void)
@ -150,23 +175,30 @@ MVFF interface
A :ref:`debugging <topic-debugging>` version of the MVFF pool
class.
When creating a debugging MVFF pool, :c:func:`mps_pool_create`
takes seven extra arguments::
When creating a debugging MVFF pool, :c:func:`mps_pool_create_k`
requires seven :term:`keyword arguments`.
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mvff_debug(),
mps_debug_option_s debug_option,
mps_size_t extend_size,
mps_size_t average_size,
mps_align_t alignment,
mps_bool_t slot_high,
mps_bool_t arena_high,
mps_bool_t first_fit)
* :c:macro:`MPS_KEY_EXTEND_BY`, :c:macro:`MPS_KEY_MEAN_SIZE`,
:c:macro:`MPS_KEY_ALIGN`, :c:macro:`MPS_KEY_MVFF_ARENA_HIGH`,
:c:macro:`MPS_KEY_MVFF_SLOT_HIGH`, and
:c:macro:`MPS_KEY_MVFF_FIRST_FIT` are as described above, and
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` specifies the debugging
:c:options. See :c:type:`mps_debug_option_s`.
``debug_option`` specifies the debugging options. See
:c:type:`mps_debug_option_s`.
.. deprecated:: starting with version 1.112.
The other arguments are the same as for :c:func:`mps_class_mvff`.
When using :c:func:`mps_pool_create`, pass the debugging
options, and other arguments like this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mvff_debug(),
mps_debug_option_s debug_option,
mps_size_t extend_size,
mps_size_t average_size,
mps_align_t alignment,
mps_bool_t slot_high,
mps_bool_t arena_high,
mps_bool_t first_fit)
.. index::

137
mps/manual/html/_sources/pool/mvt.txt
View file

@ -112,70 +112,95 @@ MVT interface
Return the :term:`pool class` for an MVT (Manual Variable
Temporal) :term:`pool`.
When creating an MVT pool, :c:func:`mps_pool_create` takes five
extra arguments::
When creating an MVT pool, :c:func:`mps_pool_create_k` requires
five :term:`keyword arguments`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mvt(),
size_t minimum_size,
size_t mean_size,
size_t maximum_size,
mps_count_t reserve_depth,
mps_count_t fragmentation_limit)
* :c:macro:`MPS_KEY_MIN_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the predicted minimum size of blocks that
will be allocated from the pool.
``minimum_size``, ``mean_size``, and ``maximum_size`` are the
predicted minimum, mean, and maximum :term:`size` of
:term:`blocks` expected to be allocated in the pool. Blocks
smaller than ``minimum_size`` and larger than ``maximum_size`` may
be allocated, but the pool is not guaranteed to manage them
space-efficiently. Furthermore, partial freeing is not supported
for blocks larger than ``maximum_size``; doing so will result in
the storage of the block never being reused. ``mean_size`` need
not be an accurate mean, although the pool will manage
``mean_size`` blocks more efficiently if it is.
* :c:macro:`MPS_KEY_MEAN_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the predicted mean size of blocks that will
be allocated from the pool.
``reserve_depth`` is the expected hysteresis of the population of
the pool. When blocks are freed, the pool will retain sufficient
storage to allocate ``reserve_depth`` blocks of ``mean_size`` for
near term allocations (rather than immediately making that storage
available to other pools).
* :c:macro:`MPS_KEY_MAX_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is the predicted maximum size of blocks that
will be allocated from the pool. Partial freeing is not
supported for blocks larger than this; doing so will
result in the storage of the block never being reused.
If a pool has a stable population, or one which only grows over
the lifetime of the pool, or one which grows steadily and then
shrinks steadily, use a reserve depth of 0.
These three arguments are *hints* to the MPS: the pool will be
less efficient if they are wrong, but the only thing that will
break is the partial freeing of large blocks.
It is always safe to use a reserve depth of 0, but if the
population typically fluctuates in a range (for example, the
client program repeatedly creates and destroys a subset of blocks
in a loop), it is more efficient for the pool to retain enough
storage to satisfy that fluctuation. For example, if a pool has an
object population that typically fluctuates between 8,000 and
10,000, use a reserve depth of 2,000.
* :c:macro:`MPS_KEY_MVT_RESERVE_DEPTH` (member ``.val.count``;
type :c:type:`mps_count_t`) is the expected hysteresis of the
population of the pool. When blocks are freed, the pool will
retain sufficient storage to allocate this many blocks of the mean
size for near term allocations (rather than immediately making
that storage available to other pools).
The reserve will not normally be available to other pools for
allocation, even when it is not used by the pool. If this is
undesirable, a reserve depth of 0 may be used for a pool whose
object population does vary, at a slight cost in efficiency. The
reserve does not guarantee any particular amount of allocation.
If a pool has a stable population, or one which only grows over
the lifetime of the pool, or one which grows steadily and then
shrinks steadily, use a reserve depth of 0.
``fragmentation_limit`` is a percentage from 1 to 100 (inclusive).
It sets an upper limit on the space overhead of MVT, in case block
death times and allocations do not correlate well. If the free
space managed by the pool as a ratio of all the space managed by
the pool exceeds ``fragmentation_limit``, the pool falls back to a
first fit allocation policy, exploiting space more efficiently at
a cost in time efficiency. A fragmentation limit of 0 would cause
the pool to operate as a first-fit pool, at a significant cost in
time efficiency: therefore this is not permitted.
It is always safe to use a reserve depth of 0, but if the
population typically fluctuates in a range (for example, the
client program repeatedly creates and destroys a subset of
blocks in a loop), it is more efficient for the pool to retain
enough storage to satisfy that fluctuation. For example, if a
pool has an object population that typically fluctuates between
8,000 and 10,000, use a reserve depth of 2,000.
A fragmentation limit of 100 causes the pool to always use
temporal fit (unless resources are exhausted). If the objects
allocated in the pool have similar lifetime expectancies, this
mode will have the best time- and space-efficiency. If the objects
have widely varying lifetime expectancies, this mode will be
time-efficient, but may be space-inefficient. An intermediate
setting can be used to limit the space-inefficiency of temporal
fit due to varying object life expectancies.
The reserve will not normally be available to other pools for
allocation, even when it is not used by the pool. If this is
undesirable, a reserve depth of 0 may be used for a pool whose
object population does vary, at a slight cost in efficiency. The
reserve does not guarantee any particular amount of allocation.
* :c:macro:`MPS_KEY_MVT_FRAG_LIMIT` (member ``.val.count``; type
:c:type:`mps_count_t`) is a percentage from 1 to 100
(inclusive). It sets an upper limit on the space overhead of an
MVT pool, in case block death times and allocations do not
correlate well. If the free space managed by the pool as a ratio
of all the space managed by the pool exceeds the fragmentation
limit, the pool falls back to a first fit allocation policy,
exploiting space more efficiently at a cost in time efficiency.
A fragmentation limit of 0 would cause the pool to operate as a
first-fit pool, at a significant cost in time efficiency:
therefore this is not permitted.
A fragmentation limit of 100 causes the pool to always use
temporal fit (unless resources are exhausted). If the objects
allocated in the pool have similar lifetime expectancies, this
mode will have the best time- and space-efficiency. If the
objects have widely varying lifetime expectancies, this mode
will be time-efficient, but may be space-inefficient. An
intermediate setting can be used to limit the space-inefficiency
of temporal fit due to varying object life expectancies.
For example, in :term:`C99`::
res = mps_pool_create_k(&pool, arena, mps_class_mvt(),
(mps_arg_s[]){{MPS_KEY_MIN_SIZE, .val.size = 4},
{MPS_KEY_MEAN_SIZE, .val.size = 32},
{MPS_KEY_MAX_SIZE, .val.size = 1024},
{MPS_KEY_MVT_RESERVE_DEPTH, .val.count = 256},
{MPS_KEY_MVT_FRAG_LIMIT, .val.count = 50},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_pool_create`, pass the arguments like
this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_mvt(),
size_t minimum_size,
size_t mean_size,
size_t maximum_size,
mps_count_t reserve_depth,
mps_count_t fragmentation_limit)
.. index::

54
mps/manual/html/_sources/pool/snc.txt
View file

@ -95,23 +95,47 @@ SNC introspection
Return the :term:`pool class` for an SNC (Stack No Check)
:term:`pool`.
When creating an SNC pool, :c:func:`mps_pool_create` takes one
extra argument::
When creating an SNC pool, :c:func:`mps_pool_create_k` requires one
:term:`keyword argument`:
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_snc(),
mps_fmt_t fmt)
* :c:macro:`MPS_KEY_FORMAT` (member ``.val.format``; type
:c:type:`mps_fmt_t`) specifies the :term:`object format` for the
objects allocated in the pool. The format must provide a
:term:`scan method`, a :term:`skip method`, and a :term:`padding
method`.
``fmt`` specifies the :term:`object format` for the objects
allocated in the pool. The format must provide a :term:`scan
method`, a :term:`skip method`, and a :term:`padding method`.
For example, in :term:`C99`::
When creating an allocation point on an SNC pool,
:c:func:`mps_ap_create` takes one extra argument::
res = mps_pool_create_k(&pool, arena, mps_class_snc(),
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = fmt},
{MPS_KEY_ARGS_END}});
mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool,
mps_rank_t rank)
.. deprecated:: starting with version 1.112.
``rank`` specifies the :term:`rank` of references in objects
allocated on this allocation point. It must be
:c:func:`mps_rank_exact`.
When using :c:func:`mps_pool_create`, pass the format like
this::
mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
mps_class_t mps_class_snc(),
mps_fmt_t fmt)
When creating an :term:`allocation point` on an SNC pool,
:c:func:`mps_ap_create_k` requires one keyword argument:
* :c:macro:`MPS_KEY_RANK` (member ``.val.rank``; type
:c:type:`mps_rank_t`) specifies the :term:`rank` of references
in objects allocated on this allocation point. It must be
:c:func:`mps_rank_exact`.
For example, in :term:`C99`::
res = mps_ap_create_k(&ap, awl_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_exact()},
{MPS_KEY_ARGS_END}});
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_ap_create`, pass the rank like this::
mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool,
mps_rank_t rank)

33
mps/manual/html/_sources/topic/allocation.txt
View file

@ -96,7 +96,7 @@ many small objects. They must be used according to the
:c:type:`mps_ap_s`.
.. c:function:: mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool, ...)
.. c:function:: mps_res_t mps_ap_create_k(mps_ap_t *ap_o, mps_pool_t pool, mps_arg_s args[])
Create an :term:`allocation point` in a :term:`pool`.
@ -105,12 +105,14 @@ many small objects. They must be used according to the
``pool`` is the pool.
``args`` are :term:`keyword arguments` specific to the pool class
to which ``pool`` belong. See the documentation for that pool
class. (Most pool classes don't take any keyword arguments; in
those cases you can pass :c:macro:`mps_args_none`.)
Returns :c:macro:`MPS_RES_OK` if successful, or another
:term:`result code` if not.
Some pool classes require additional arguments to be passed to
:c:func:`mps_ap_create`. See the documentation for the pool class.
.. warning::
An allocation point must not be used by more than one
@ -124,9 +126,28 @@ many small objects. They must be used according to the
``va_list`` mechanism.
.. c:function:: mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool, ...)
.. deprecated:: starting with version 1.112.
Use :c:func:`mps_ap_create_k` instead: the :term:`keyword
arguments` interface is more reliable and produces better
error messages.
An alternative to :c:func:`mps_ap_create_k` that takes its extra
arguments using the standard :term:`C` variable argument list
mechanism.
.. c:function:: mps_res_t mps_ap_create_v(mps_ap_t *ap_o, mps_pool_t pool, va_list args)
An alternative to :c:func:`mps_ap_create` that takes its extra
.. deprecated:: starting with version 1.112.
Use :c:func:`mps_ap_create_k` instead: the :term:`keyword
arguments` interface is more reliable and produces better
error messages.
An alternative to :c:func:`mps_ap_create_k` that takes its extra
arguments using the standard :term:`C` ``va_list`` mechanism.
@ -642,7 +663,7 @@ branch prediction should work well since the test almost never fails).
synchronization in a multi-threaded environment.
Create an allocation point for a pool by calling
:c:func:`mps_ap_create`, and allocate memory via one by calling
:c:func:`mps_ap_create_k`, and allocate memory via one by calling
:c:func:`mps_reserve` and :c:func:`mps_commit`.

149
mps/manual/html/_sources/topic/arena.txt
View file

@ -14,7 +14,7 @@ Arenas
An arena is an object that encapsulates the state of the Memory Pool
System, and tells it where to get the memory it manages. You typically
start a session with the MPS by creating an arena with
:c:func:`mps_arena_create` and end the session by destroying it with
:c:func:`mps_arena_create_k` and end the session by destroying it with
:c:func:`mps_arena_destroy`. The only function you might need to call
before making an arena is :c:func:`mps_telemetry_control`.
@ -76,28 +76,14 @@ the way that they acquire the memory to be managed.
.. c:function:: mps_res_t mps_arena_create_k(mps_arena_t *arena_o, mps_arena_class_t arena_class, mps_arg_s args[])
Create an :term:`arena`.
``arena_o`` points to a location that will hold a pointer to the new
arena.
``arena_class`` is the :term:`arena class`.
``args`` are :ref:`topic-interface-keywords` specific to the arena
class. See the documentation for the arena class.
.. c:function:: mps_res_t mps_arena_create(mps_arena_t *arena_o, mps_arena_class_t arena_class, ...)
Create an :term:`arena`.
``arena_o`` points to a location that will hold a pointer to the new
arena.
``arena_class`` is the :term:`arena class`.
Some arena classes require additional arguments to be passed to
:c:func:`mps_arena_create`. See the documentation for the arena
class.
``args`` are :term:`keyword arguments` specific to the arena
class. See the documentation for the arena class.
Returns :c:macro:`MPS_RES_OK` if the arena is created
successfully, or another :term:`result code` otherwise.
@ -105,17 +91,31 @@ the way that they acquire the memory to be managed.
The arena persists until it is destroyed by calling
:c:func:`mps_arena_destroy`.
.. note::
There's an alternative function :c:func:`mps_arena_create_v`
that takes its extra arguments using the standard :term:`C`
``va_list`` mechanism.
.. c:function:: mps_res_t mps_arena_create(mps_arena_t *arena_o, mps_arena_class_t arena_class, ...)
.. deprecated:: starting with version 1.112.
Use :c:func:`mps_arena_create_k` instead: the :term:`keyword
arguments` interface is more reliable and produces better
error messages.
An alternative to :c:func:`mps_arena_create_k` that takes its
extra arguments using the standard :term:`C` variable argument
list mechanism.
.. c:function:: mps_res_t mps_arena_create_v(mps_arena_t *arena_o, mps_arena_class_t arena_class, va_list args)
An alternative to :c:func:`mps_arena_create` that takes its extra
arguments using the standard :term:`C` ``va_list`` mechanism.
.. deprecated:: starting with version 1.112.
Use :c:func:`mps_arena_create_k` instead: the :term:`keyword
arguments` interface is more reliable and produces better
error messages.
An alternative to :c:func:`mps_arena_create_k` that takes its
extra arguments using the standard :term:`C` ``va_list``
mechanism.
.. c:function:: void mps_arena_destroy(mps_arena_t arena)
@ -156,30 +156,24 @@ Client arenas
program`. This memory chunk is passed when the arena is created.
When creating a client arena, :c:func:`mps_arena_create_k` requires two
:ref:`topic-interface-keywords`:
* ``MPS_KEY_ARENA_CL_BASE`` (type ``mps_addr_t``) is the
:term:`address` of the chunk of memory that will be managed by the
arena.
:term:`keyword arguments`:
* :c:macro:`MPS_KEY_ARENA_CL_ADDR` (member ``.val.addr``; type
:c:type:`mps_addr_t`) is the :term:`address` of the chunk of memory
that will be managed by the arena.
* :c:macro:`MPS_KEY_ARENA_SIZE` (member ``.val.size``; type
:c:type:`size_t`) is its size.
For example (in :term:`C99`)::
* ``MPS_KEY_ARENA_SIZE`` (type ``size_t``) is its size.
For example (in C99)::
res = mps_arena_create_k(&arena, mps_arena_class_cl(),
(mps_arg_s[]){{MPS_KEY_ARENA_CL_BASE, .val.addr = base},
(mps_arg_s[]){{MPS_KEY_ARENA_CL_ADDR, .val.addr = base},
{MPS_KEY_ARENA_SIZE, .val.size = size},
{MPS_KEY_ARGS_END}});
When creating a client arena, :c:func:`mps_arena_create` takes the
these arguments like this::
mps_res_t mps_arena_create(mps_arena_t *arena_o,
mps_arena_class_t mps_arena_class_cl,
size_t size, mps_addr_t base)
If the chunk is too small to hold the internal arena structures,
:c:func:`mps_arena_create` returns :c:macro:`MPS_RES_MEMORY`. In
:c:func:`mps_arena_create_k` returns :c:macro:`MPS_RES_MEMORY`. In
this case, you need to use a (much) larger chunk.
.. note::
@ -189,6 +183,15 @@ Client arenas
Client arenas have no mechanism for returning unused memory.
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_arena_create`, pass the size and base
address like this::
mps_res_t mps_arena_create(mps_arena_t *arena_o,
mps_arena_class_t mps_arena_class_cl,
size_t size, mps_addr_t base)
.. c:function:: mps_res_t mps_arena_extend(mps_arena_t arena, mps_addr_t base, size_t size)
@ -229,13 +232,13 @@ Virtual memory arenas
more efficient.
When creating a virtual memory arena, :c:func:`mps_arena_create_k`
requires one
:ref:`topic-interface-keywords`:
* ``MPS_KEY_ARENA_SIZE`` (type ``size_t``)
For example (in C99)::
requires one :term:`keyword argument`:
* :c:macro:`MPS_KEY_ARENA_SIZE` (member ``.val.size``; type
:c:type:`size_t`).
For example (in :term:`C99`)::
res = mps_arena_create_k(&arena, mps_arena_class_cl(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = size},
{MPS_KEY_ARGS_END}});
@ -256,38 +259,41 @@ Virtual memory arenas
more times it has to extend its address space, the less
efficient garbage collection will become.
An optional :ref:`topic-interface-keywords` may be passed, but is
An optional :term:`keyword argument` may be passed, but is
only used on the Windows operating system:
* ``MPS_KEY_VM_W3_TOP_DOWN`` (type ``mps_bool_t``)
* :c:macro:`MPS_KEY_VMW3_TOP_DOWN` (member ``.val.b``; type
:c:type:`mps_bool_t`).
If true, the arena will allocate address space starting at the
highest possible address and working downwards through memory.
.. note::
This causes the arena to pass the ``MEM_TOP_DOWN`` flag to
`VirtualAlloc`_.
.. _VirtualAlloc: http://msdn.microsoft.com/en-us/library/windows/desktop/aa366887%28v=vs.85%29.aspx
When creating a virtual memory arena, :c:func:`mps_arena_create`
takes one extra argument::
mps_res_t mps_arena_create(mps_arena_t *arena_o,
mps_arena_class_t arena_class_vm(),
size_t size)
If the MPS fails to reserve adequate address space to place the
arena in, :c:func:`mps_arena_create` returns
arena in, :c:func:`mps_arena_create_k` returns
:c:macro:`MPS_RES_RESOURCE`. Possibly this means that other parts
of the program are reserving too much virtual memory.
If the MPS fails to allocate memory for the internal arena
structures, :c:func:`mps_arena_create` returns
structures, :c:func:`mps_arena_create_k` returns
:c:macro:`MPS_RES_MEMORY`. Either ``size`` was far too small or
the operating system refused to provide enough memory.
.. deprecated:: starting with version 1.112.
When using :c:func:`mps_arena_create`, pass the size like
this::
mps_res_t mps_arena_create(mps_arena_t *arena_o,
mps_arena_class_t arena_class_vm(),
size_t size)
.. index::
single: arena; properties
@ -410,16 +416,17 @@ Arena properties
For a :term:`client arena`, this is the sum of the usable portions
of the chunks of memory passed to the arena by the :term:`client
program` via :c:func:`mps_arena_create` and
program` via :c:func:`mps_arena_create_k` and
:c:func:`mps_arena_extend`.
.. note::
For a client arena, the reserved address may be lower than the
sum of the ``size`` arguments passed to
:c:func:`mps_arena_create` and :c:func:`mps_arena_extend`,
because the arena may be unable to use the whole of each chunk
for reasons of alignment.
sum of the :c:macro:`MPS_KEY_ARENA_SIZE` keyword argument
passed to :c:func:`mps_arena_create_k` and the ``size``
arguments passed to :c:func:`mps_arena_extend`, because the
arena may be unable to use the whole of each chunk for reasons
of alignment.
.. c:function:: size_t mps_arena_spare_commit_limit(mps_arena_t arena)
@ -545,7 +552,7 @@ can only be called in this state.
.. c:function:: void mps_arena_clamp(mps_arena_t arena)
Put an :term:`arena` into the :term:`clamped state`.
``arena`` is the arena to clamp.
In the clamped state, no object motion will occur and the
@ -752,7 +759,7 @@ Arena introspection
Introspection functions covered in other chapters are:
* :c:func:`mps_addr_fmt`: determine the :term:`object format` to
which an address belongs;
which an address belongs;
* :c:func:`mps_arena_formatted_objects_walk`: visit all
:term:`formatted objects` in an arena;
* :c:func:`mps_arena_roots_walk`: visit all references in
@ -763,7 +770,7 @@ Arena introspection
.. c:function:: mps_bool_t mps_arena_has_addr(mps_arena_t arena, mps_addr_t addr)
Test whether an :term:`address` is managed by an :term:`arena`.
Test whether an :term:`address` is managed by an :term:`arena`.
``arena`` is an arena.

13
mps/manual/html/_sources/topic/debugging.txt
View file

@ -71,15 +71,20 @@ For example::
};
mps_pool_t pool;
mps_res_t res;
res = mps_pool_create(&pool, arena, mps_class_ams_debug(),
&debug_options, &fmt, &chain)
res = mps_pool_create_k(&pool, arena, mps_class_ams_debug(),
(mps_arg_s[]){{MPS_KEY_POOL_DEBUG_OPTIONS, .val.pool_debug_options = &debug_options},
{MPS_KEY_FORMAT, .val.format = &fmt},
{MPS_KEY_CHAIN, .val.chain = &chain},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("can't create debug pool");
.. c:type:: mps_pool_debug_option_s
The type of the structure used to pass options to
:c:func:`mps_pool_create` for debugging :term:`pool classes`. ::
The type of the structure passed as the
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` keyword argument to
:c:func:`mps_pool_create_k` when creating a debugging :term:`pool
class`. ::
typedef struct mps_pool_debug_option_s {
void *fence_template;

2
mps/manual/html/_sources/topic/error.txt
View file

@ -227,7 +227,7 @@ this documentation.
``format.c: SigCheck Format: format``
The client program called :c:func:`mps_pool_create` for a
The client program called :c:func:`mps_pool_create_k` for a
:term:`pool class` like :ref:`pool-amc` that requires a
:term:`object format`, but passed something other than a
:c:type:`mps_fmt_t` for this argument.

4
mps/manual/html/_sources/topic/format.txt
View file

@ -92,7 +92,9 @@ For example::
if (res != MPS_RES_OK) error("Couldn't create obj format");
/* obj_fmt created successfully */
res = mps_pool_create(&obj_pool, arena, pool_class, obj_fmt);
res = mps_pool_create_k(&obj_pool, arena, pool_class,
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create obj pool");

1
mps/manual/html/_sources/topic/index.txt
View file

@ -7,6 +7,7 @@ Reference
:numbered:
interface
keyword
error
arena
pool

47
mps/manual/html/_sources/topic/interface.txt
View file

@ -54,8 +54,8 @@ Support policy
Language
--------
1. The MPS public interface conforms to ANSI/ISO Standard C (IEC
9899:1990).
1. The MPS public interface conforms to :ref:`ANSI/ISO Standard C (IEC
9899:1990) <C1990>`.
.. index::
@ -171,6 +171,10 @@ Functions
7. In/out parameters have names ending with ``_io``.
8. A function that takes optional arguments does so in the form of an
array of keyword argument structures. These functions have names
ending with ``_k``. See :ref:`topic-keyword`.
.. index::
single: interface; type punning
@ -258,45 +262,6 @@ Macros
separately.
.. _topic-interface-keywords:
Keyword arguments
-----------------
Some functions take :term:`keyword arguments` in order to pass values
that might be optional, or are only required in some circumstances. For
example, :ref:`client arenas <topic-arena-client>` require a base address. These
arguments are passed in a keyword argument array, like this::
mps_res_t res;
mps_arena_t arena;
mps_arg_s args[3];
args[0].key = MPS_KEY_ARENA_SIZE;
args[0].val.size = 6553600;
args[1].key = MPS_KEY_ARENA_CL_BASE;
args[1].val.addr = base_address;
args[2].key = MPS_KEY_ARGS_END;
res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);
If you are writing C99, you can write this more concisely as::
mps_res_t res;
mps_arena_t arena;
res = mps_arena_create_k(&arena, mps_arena_class_cl(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = 6553600},
{MPS_KEY_ARENA_CL_BASE, .val.addr = base_address},
{MPS_KEY_ARGS_END}});
The argument array must not be ``NULL``, and must end with
``MPS_KEY_ARGS_END``.
On return, the keyword argument array will be *modified* to remove any
arguments that have been used. If all arguments have been used the
first element key will be MPS_KEY_ARGS_END.
If you don't want to pass any arguments, you can either call the equivalent function that does not take
.. _topic-interface-general:
General types

190
mps/manual/html/_sources/topic/keyword.txt Normal file
View file

@ -0,0 +1,190 @@
.. index::
pair: arguments; keyword
.. _topic-keyword:
Keyword arguments
-----------------
Some functions in the MPS interface take :term:`keyword arguments` in
order to pass values that might be optional, or are only required in
some circumstances. For example, the function
:c:func:`mps_arena_create_k` creates any class of :term:`arena`, but
:term:`client arenas` require you to specify a base address. These
arguments are passed in a keyword argument array, like this::
mps_res_t res;
mps_arena_t arena;
mps_arg_s args[3];
args[0].key = MPS_KEY_ARENA_SIZE;
args[0].val.size = 6553600;
args[1].key = MPS_KEY_ARENA_CL_ADDR;
args[1].val.addr = base_address;
args[2].key = MPS_KEY_ARGS_END;
res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);
Each keyword argument in the array is a structure of type
:c:type:`mps_arg_s`.
For convenience and robustness, the MPS interface includes macros to
help with forming keyword argument lists::
MPS_ARGS_BEGIN(args) {
MPS_ARGS_ADD(args, MPS_KEY_ARENA_SIZE, size, 6553600);
MPS_ARGS_ADD(args, MPS_KEY_ARENA_CL_ADDR, addr, base_address);
MPS_ARGS_DONE(args);
res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);
} MPS_ARGS_END(args);
But if you are writing :term:`C99`, you can write this more concisely as::
mps_res_t res;
mps_arena_t arena;
res = mps_arena_create_k(&arena, mps_arena_class_cl(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = 6553600},
{MPS_KEY_ARENA_CL_ADDR, .val.addr = base_address},
{MPS_KEY_ARGS_END}});
The argument array must not be ``NULL``, and must end with
:c:macro:`MPS_KEY_ARGS_END`. If you don't want to pass any arguments, you can
either call the equivalent function that does not take keyword arguments
(named without the ``_k``) or pass :c:macro:`mps_args_none`.
When a function that takes keyword arguments returns, the keyword
argument array has been *modified* to remove any arguments that have
been used. If all arguments have been used, the first element key is
now :c:macro:`MPS_KEY_ARGS_END`.
.. c:type:: mps_arg_s
The type of the structure used to represent a single
:term:`keyword argument` to a function. ::
typedef struct mps_arg_s {
mps_key_t key;
union {
mps_bool_t b;
char c;
const char *string;
int i;
unsigned u;
long l;
unsigned long ul;
size_t size;
mps_addr_t addr;
mps_fmt_t format;
mps_chain_t chain;
struct mps_pool_debug_option_s *pool_debug_options;
mps_addr_t (*addr_method)(mps_addr_t);
mps_align_t align;
mps_word_t count;
void *p;
mps_rank_t rank;
} val;
} mps_arg_s;
``key`` identifies the key. It must be one of the legal values
of :c:type:`mps_key_t` listed in the documentation for that type.
``val`` is the corresponding value. The documentation for each
value of the type :c:type:`mps_key_t` explains which structure
member is used by that keyword.
.. c:macro:: mps_args_none
An array of :c:type:`mps_arg_s` representing the empty list of
keyword arguments. Equivalent to::
mps_arg_s mps_args_none[] = {{MPS_KEY_ARGS_END}};
.. c:type:: mps_key_t
The type of :term:`keyword argument` keys. Must take one of the
following values:
======================================== ====================== ==========================================================
Keyword Value slot See
======================================== ====================== ==========================================================
:c:macro:`MPS_KEY_ARGS_END` *none* *see above*
:c:macro:`MPS_KEY_ALIGN` ``align`` :c:func:`mps_class_mvff`
:c:macro:`MPS_KEY_AMS_SUPPORT_AMBIGUOUS` ``b`` :c:func:`mps_class_ams`
:c:macro:`MPS_KEY_ARENA_CL_ADDR` ``addr`` :c:func:`mps_arena_class_cl`
:c:macro:`MPS_KEY_ARENA_SIZE` ``size`` :c:func:`mps_arena_class_vm`, :c:func:`mps_arena_class_cl`
:c:macro:`MPS_KEY_AWL_FIND_DEPENDENT` ``addr_method`` :c:func:`mps_class_awl`
:c:macro:`MPS_KEY_CHAIN` ``chain`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_ams`
:c:macro:`MPS_KEY_EXTEND_BY` ``size`` :c:func:`mps_class_mfs`, :c:func:`mps_class_mv`, :c:func:`mps_class_mvff`
:c:macro:`MPS_KEY_FORMAT` ``format`` :c:func:`mps_class_amc`, :c:func:`mps_class_amcz`, :c:func:`mps_class_ams`, :c:func:`mps_class_awl`, :c:func:`mps_class_lo` , :c:func:`mps_class_snc`
:c:macro:`MPS_KEY_MAX_SIZE` ``size`` :c:func:`mps_class_mv`
:c:macro:`MPS_KEY_MEAN_SIZE` ``size`` :c:func:`mps_class_mv`, :c:func:`mps_class_mvt`, :c:func:`mps_class_mvff`
:c:macro:`MPS_KEY_MFS_UNIT_SIZE` ``size`` :c:func:`mps_class_mfs`
:c:macro:`MPS_KEY_MIN_SIZE` ``size`` :c:func:`mps_class_mvt`
:c:macro:`MPS_KEY_MVFF_ARENA_HIGH` ``b`` :c:func:`mps_class_mvff`
:c:macro:`MPS_KEY_MVFF_FIRST_FIT` ``b`` :c:func:`mps_class_mvff`
:c:macro:`MPS_KEY_MVFF_SLOT_HIGH` ``b`` :c:func:`mps_class_mvff`
:c:macro:`MPS_KEY_MVT_FRAG_LIMIT` ``count`` :c:func:`mps_class_mvt`
:c:macro:`MPS_KEY_MVT_RESERVE_DEPTH` ``count`` :c:func:`mps_class_mvt`
:c:macro:`MPS_KEY_POOL_DEBUG_OPTIONS` ``pool_debug_options`` :c:func:`mps_class_ams_debug`, :c:func:`mps_class_mv_debug`, :c:func:`mps_class_mvff_debug`
:c:macro:`MPS_KEY_RANK` ``rank`` :c:func:`mps_class_awl`, :c:func:`mps_class_snc`
:c:macro:`MPS_KEY_VMW3_TOP_DOWN` ``b`` :c:func:`mps_arena_class_vm`
======================================== ====================== ==========================================================
.. c:function:: MPS_ARGS_BEGIN(args)
Start construction of a list of keyword arguments. This macro must
be used like this::
MPS_ARGS_BEGIN(args) {
MPS_ARGS_ADD(args, MPS_KEY_ARENA_SIZE, size, 6553600);
MPS_ARGS_ADD(args, MPS_KEY_ARENA_CL_ADDR, addr, base_address);
MPS_ARGS_DONE(args);
res = mps_arena_create_k(&arena, mps_arena_class_cl(), args);
} MPS_ARGS_END(args);
That is, you must call :c:func:`MPS_ARGS_ADD` zero or more times,
and then call :c:func:`MPS_ARGS_DONE` before passing the arguments
to a function.
``args`` is the name of the array that contains the keyword
arguments. The array is stack-allocated, and exists between
:c:macro:`MPS_ARGS_BEGIN` and :c:macro:`MPS_ARGS_END`.
It is safe to nest blocks created by :c:macro:`MPS_ARGS_BEGIN` and
:c:macro:`MPS_ARGS_END`.
.. c:function:: MPS_ARGS_ADD(mps_arg_s args[], mps_key_t key, value)
Add an argument to a list of keyword arguments. This macro must be
used only between :c:macro:`MPS_ARGS_BEGIN` and
:c:macro:`MPS_ARGS_END`.
``args`` is the name of array that contains the keyword arguments.
It must match the argument to the preceding call to
:c:func:`MPS_ARGS_BEGIN`.
.. c:function:: MPS_ARGS_DONE(args)
Finalize a list of keyword arguments. This macro must be used only
between :c:macro:`MPS_ARGS_BEGIN` and :c:macro:`MPS_ARGS_END`.
``args`` is the name of array that contains the keyword arguments.
It must match the argument to the preceding call to
:c:func:`MPS_ARGS_BEGIN`.
After calling this macro, the array ``args`` is ready to pass to a
function.
.. c:function:: MPS_ARGS_END(args)
Finish using a list of keyword arguments whose construction was
started by :c:func:`MPS_ARGS_BEGIN`.
``args`` is the name of array that contains the keyword arguments.
It must match the argument to the preceding call to
:c:func:`MPS_ARGS_BEGIN`.

30
mps/manual/html/_sources/topic/pool.txt
View file

@ -19,7 +19,7 @@ making it available for allocation.
:c:func:`mps_alloc` or via an :term:`allocation point`.
.. c:function:: mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, ...)
.. c:function:: mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, mps_arg_s args[])
Create a :term:`pool` in an :term:`arena`.
@ -30,9 +30,8 @@ making it available for allocation.
``class`` is the :term:`pool class` of the new pool.
Some pool classes require additional arguments to be passed to
:c:func:`mps_pool_create`. See the documentation for the pool
class.
``args`` are :term:`keyword arguments` specific to the pool class.
See the documentation for the pool class.
Returns :c:macro:`MPS_RES_OK` if the pool is created successfully,
or another :term:`result code` otherwise.
@ -40,16 +39,29 @@ making it available for allocation.
The pool persists until it is destroyed by calling
:c:func:`mps_pool_destroy`.
.. note::
There's an alternative function :c:func:`pool_create_v` that
takes its extra arguments using the standard :term:`C`
``va_list`` mechanism.
.. c:function:: mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, ...)
.. deprecated:: starting with version 1.112.
Use :c:func:`mps_pool_create_k` instead: the :term:`keyword
arguments` interface is more reliable and produces better
error messages.
An alternative to :c:func:`mps_pool_create_k` that takes its
extra arguments using the standard :term:`C` variable argument
list mechanism.
.. c:function:: mps_res_t mps_pool_create_v(mps_pool_t *pool_o, mps_arena_t arena, mps_class_t class, va_list args)
An alternative to :c:func:`mps_pool_create` that takes its extra
.. deprecated:: starting with version 1.112.
Use :c:func:`mps_pool_create_k` instead: the :term:`keyword
arguments` interface is more reliable and produces better
error messages.
An alternative to :c:func:`mps_pool_create_k` that takes its extra
arguments using the standard :term:`C` ``va_list`` mechanism.

4
mps/manual/html/_static/pygments.css
View file

@ -13,11 +13,11 @@
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #333333 } /* Generic.Output */
.highlight .go { color: #303030 } /* Generic.Output */
.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */

2
mps/manual/html/design/arena.html
View file

@ -286,7 +286,7 @@ <h3>1.6.3. Tracts<a class="headerlink" href="#tracts" title="Permalink to this h
<p><span class="target" id="design.mps.arena.tract.if.tractofaddr"></span><a class="mpstag reference internal" href="#design.mps.arena.tract.if.tractofaddr">.tract.if.tractofaddr:</a> The function <tt class="xref c c-func docutils literal"><span class="pre">TractOfAddr()</span></tt>
finds the tract corresponding to an address in memory. (See
<a class="reference internal" href="#design.mps.arena.req.fun.trans">.req.fun.trans</a>):</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">Bool</span> <span class="nf">TractOfAddr</span><span class="p">(</span><span class="n">Tract</span> <span class="o">*</span><span class="n">tractReturn</span><span class="p">,</span> <span class="n">Arena</span> <span class="n">arena</span><span class="p">,</span> <span class="n">Addr</span> <span class="n">addr</span><span class="p">);</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">Bool</span> <span class="n">TractOfAddr</span><span class="p">(</span><span class="n">Tract</span> <span class="o">*</span><span class="n">tractReturn</span><span class="p">,</span> <span class="n">Arena</span> <span class="n">arena</span><span class="p">,</span> <span class="n">Addr</span> <span class="n">addr</span><span class="p">);</span>
</pre></div>
</div>
<p>If <tt class="docutils literal"><span class="pre">addr</span></tt> is an address which has been allocated to some pool, then

2
mps/manual/html/design/bt.html
View file

@ -426,7 +426,7 @@ <h2>2.9. Interface<a class="headerlink" href="#interface" title="Permalink to th
<p><span class="target" id="design.mps.bt.if.find.general"></span><a class="mpstag reference internal" href="#design.mps.bt.if.find.general">.if.find.general:</a> There are four functions (below) to find
reset ranges. All the functions have the same prototype (for
symmetry):</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">Bool</span> <span class="nf">find</span><span class="p">(</span><span class="n">Index</span> <span class="o">*</span><span class="n">baseReturn</span><span class="p">,</span> <span class="n">Index</span> <span class="o">*</span><span class="n">limitReturn</span><span class="p">,</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">Bool</span> <span class="n">find</span><span class="p">(</span><span class="n">Index</span> <span class="o">*</span><span class="n">baseReturn</span><span class="p">,</span> <span class="n">Index</span> <span class="o">*</span><span class="n">limitReturn</span><span class="p">,</span>
<span class="n">BT</span> <span class="n">bt</span><span class="p">,</span>
<span class="n">Index</span> <span class="n">searchBase</span><span class="p">,</span> <span class="n">Index</span> <span class="n">searchLimit</span><span class="p">,</span>
<span class="n">Count</span> <span class="n">length</span><span class="p">);</span>

10
mps/manual/html/design/config.html
View file

@ -416,19 +416,19 @@ <h3>7.8.3. Configuring module implementations<a class="headerlink" href="#config
<p>For example, this isn&#8217;t allowed, because there is a change in the
interface:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(PROT_FOO)</span>
<span class="kt">void</span> <span class="nf">ProtSpong</span><span class="p">(</span><span class="n">Foo</span> <span class="n">foo</span><span class="p">,</span> <span class="n">Bar</span> <span class="n">bar</span><span class="p">);</span>
<span class="kt">void</span> <span class="n">ProtSpong</span><span class="p">(</span><span class="n">Foo</span> <span class="n">foo</span><span class="p">,</span> <span class="n">Bar</span> <span class="n">bar</span><span class="p">);</span>
<span class="cp">#else</span>
<span class="kt">int</span> <span class="nf">ProtSpong</span><span class="p">(</span><span class="n">Bar</span> <span class="n">bar</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">foo</span><span class="p">);</span>
<span class="kt">int</span> <span class="n">ProtSpong</span><span class="p">(</span><span class="n">Bar</span> <span class="n">bar</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">foo</span><span class="p">);</span>
<span class="cp">#endif</span>
</pre></div>
</div>
<p>This example is allowed:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#ifdef PROTECTION</span>
<span class="kt">void</span> <span class="nf">ProtSync</span><span class="p">(</span><span class="n">Space</span> <span class="n">space</span><span class="p">);</span>
<span class="cm">/* more decls. */</span>
<span class="kt">void</span> <span class="n">ProtSync</span><span class="p">(</span><span class="n">Space</span> <span class="n">space</span><span class="p">);</span>
<span class="cp">/* more decls. */</span>
<span class="cp">#else </span><span class="cm">/* PROTECTION not */</span><span class="cp"></span>
<span class="cp">#define ProtSync(space) NOOP</span>
<span class="cm">/* more decls. */</span>
<span class="cp">/* more decls. */</span>
<span class="cp">#endif </span><span class="cm">/* PROTECTION */</span><span class="cp"></span>
</pre></div>
</div>

84
mps/manual/html/genindex.html
View file

@ -537,6 +537,17 @@ <h2 id="A">A</h2>
</dt>
<dt>
arguments
</dt>
<dd><dl>
<dt><a href="topic/keyword.html#index-0">keyword</a>
</dt>
</dl></dd>
<dt><a href="guide/debug.html#index-2">ASLR</a>
</dt>
@ -896,6 +907,18 @@ <h2 id="C">C</h2>
</dt>
<dt><a href="glossary/c.html#term-c89"><strong>C89</strong></a>
</dt>
<dt><a href="glossary/c.html#term-c90"><strong>C90</strong></a>
</dt>
<dt><a href="glossary/c.html#term-c99"><strong>C99</strong></a>
</dt>
<dt><a href="glossary/c.html#term-cache-1"><strong>cache (1)</strong></a>
</dt>
@ -1075,6 +1098,8 @@ <h2 id="C">C</h2>
<dt><a href="mmref/lang.html#term-cobol"><strong>COBOL</strong></a>
</dt>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt>
code
@ -1086,8 +1111,6 @@ <h2 id="C">C</h2>
</dt>
</dl></dd>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="glossary/c.html#term-collect"><strong>collect</strong></a>
</dt>
@ -2233,9 +2256,24 @@ <h2 id="K">K</h2>
<dt><a href="glossary/k.html#term-kb"><strong>kB</strong></a>
</dt>
<dt>
keyword
</dt>
<dd><dl>
<dt><a href="topic/keyword.html#index-0">arguments</a>
</dt>
</dl></dd>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="glossary/k.html#term-keyword-argument"><strong>keyword argument</strong></a>
</dt>
<dt><a href="glossary/k.html#term-kilobyte"><strong>kilobyte</strong></a>
</dt>
@ -2785,6 +2823,10 @@ <h2 id="M">M</h2>
</dt>
<dt><a href="topic/allocation.html#mps_ap_create_k">mps_ap_create_k (C function)</a>
</dt>
<dt><a href="topic/allocation.html#mps_ap_create_v">mps_ap_create_v (C function)</a>
</dt>
@ -2861,6 +2903,10 @@ <h2 id="M">M</h2>
</dt>
<dt><a href="topic/arena.html#mps_arena_create_k">mps_arena_create_k (C function)</a>
</dt>
<dt><a href="topic/arena.html#mps_arena_create_v">mps_arena_create_v (C function)</a>
</dt>
@ -2937,6 +2983,30 @@ <h2 id="M">M</h2>
</dt>
<dt><a href="topic/keyword.html#mps_arg_s">mps_arg_s (C type)</a>
</dt>
<dt><a href="topic/keyword.html#MPS_ARGS_ADD">MPS_ARGS_ADD (C function)</a>
</dt>
<dt><a href="topic/keyword.html#MPS_ARGS_BEGIN">MPS_ARGS_BEGIN (C function)</a>
</dt>
<dt><a href="topic/keyword.html#MPS_ARGS_DONE">MPS_ARGS_DONE (C function)</a>
</dt>
<dt><a href="topic/keyword.html#MPS_ARGS_END">MPS_ARGS_END (C function)</a>
</dt>
<dt><a href="topic/keyword.html#mps_args_none">mps_args_none (C macro)</a>
</dt>
<dt><a href="pool/awl.html#mps_awl_find_dependent_t">mps_awl_find_dependent_t (C type)</a>
</dt>
@ -3128,6 +3198,8 @@ <h2 id="M">M</h2>
<dt><a href="topic/format.html#mps_fmt_isfwd_t">mps_fmt_isfwd_t (C type)</a>
</dt>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="topic/format.html#mps_fmt_pad_t">mps_fmt_pad_t (C type)</a>
</dt>
@ -3144,8 +3216,6 @@ <h2 id="M">M</h2>
<dt><a href="topic/format.html#mps_fmt_skip_t">mps_fmt_skip_t (C type)</a>
</dt>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="topic/format.html#mps_fmt_t">mps_fmt_t (C type)</a>
</dt>
@ -3187,6 +3257,10 @@ <h2 id="M">M</h2>
</dt>
<dt><a href="topic/keyword.html#mps_key_t">mps_key_t (C type)</a>
</dt>
<dt><a href="topic/interface.html#mps_label_t">mps_label_t (C type)</a>
</dt>
@ -3427,7 +3501,7 @@ <h2 id="M">M</h2>
</dt>
<dt><a href="topic/pool.html#mps_pool_create">mps_pool_create (C function)</a>
<dt><a href="topic/pool.html#mps_pool_create">mps_pool_create (C function)</a>, <a href="topic/pool.html#mps_pool_create">[1]</a>
</dt>

39
mps/manual/html/glossary/c.html
View file

@ -83,6 +83,45 @@ <h3>Navigation</h3>
| Y
| <a class="reference internal" href="z.html#glossary-z"><em>Z</em></a></p>
<dl class="glossary docutils">
<dt id="term-c89">C89</dt>
<dd><div class="admonition-see first last admonition">
<p class="first admonition-title">See</p>
<p class="last"><a class="reference internal" href="#term-c90"><em class="xref std std-term">C90</em></a>.</p>
</div>
</dd>
<dt id="term-c90">C90</dt>
<dd><div class="admonition-also-known-as first admonition">
<p class="first admonition-title">Also known as</p>
<p class="last"><em>C89</em>.</p>
</div>
<p>A revision of the ANSI/ISO Standard for the <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
programming language. Although more than twenty years old, it
remains the only form of Standard C that is supported by all
the major compilers, including Microsoft Visual C.</p>
<div class="admonition-in-the-mps admonition">
<p class="first admonition-title">In the MPS</p>
<p class="last">The public interface conforms to this standard. See
<a class="reference internal" href="../topic/interface.html#topic-interface"><em>Interface conventions</em></a>.</p>
</div>
<div class="admonition-related-publication last admonition">
<p class="first admonition-title">Related publication</p>
<p class="last"><a class="reference internal" href="../mmref/bib.html#c1990"><em>ISO/IEC 9899:1990</em></a>.</p>
</div>
</dd>
<dt id="term-c99">C99</dt>
<dd><p class="first">A revision of the ANSI/ISO Standard for C the <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
programming language.</p>
<div class="admonition-in-the-mps admonition">
<p class="first admonition-title">In the MPS</p>
<p class="last"><a class="reference internal" href="k.html#term-keyword-argument"><em class="xref std std-term">Keyword arguments</em></a> can be conveniently passed to
functions using C99&#8217;s compound literal syntax. See
<a class="reference internal" href="../topic/keyword.html#topic-keyword"><em>Keyword arguments</em></a>.</p>
</div>
<div class="admonition-related-publication last admonition">
<p class="first admonition-title">Related publication</p>
<p class="last"><a class="reference internal" href="../mmref/bib.html#c1999"><em>ISO/IEC 9899:1999</em></a>.</p>
</div>
</dd>
<dt id="term-cache-1">cache<sup>(1)</sup></dt>
<dd><div class="admonition-also-known-as first admonition">
<p class="first admonition-title">Also known as</p>

10
mps/manual/html/glossary/k.html
View file

@ -89,6 +89,16 @@ <h3>Navigation</h3>
<p class="last"><a class="reference internal" href="#term-kilobyte"><em class="xref std std-term">kilobyte</em></a>.</p>
</div>
</dd>
<dt id="term-keyword-argument">keyword argument</dt>
<dd><p class="first">An optional argument to a function call, identified by an
associated keyword.</p>
<div class="admonition-in-the-mps last admonition">
<p class="first admonition-title">In the MPS</p>
<p class="last">Keyword arguments are passed to functions in the MPS
interface as arrays of structures of type
<a class="reference internal" href="../topic/keyword.html#mps_arg_s" title="mps_arg_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_arg_s</span></tt></a>. See <a class="reference internal" href="../topic/keyword.html#topic-keyword"><em>Keyword arguments</em></a>.</p>
</div>
</dd>
<dt id="term-kilobyte">kilobyte</dt>
<dd><div class="admonition-also-known-as first admonition">
<p class="first admonition-title">Also known as</p>

135
mps/manual/html/guide/advanced.html
View file

@ -61,8 +61,8 @@ <h3>Navigation</h3>
<p>In Scheme, an open file is represented by a <em>port</em>. In the toy Scheme
interpreter, a port is a wrapper around a standard C file handle:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">port_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PORT */</span>
<span class="kt">obj_t</span> <span class="n">name</span><span class="p">;</span> <span class="cm">/* name of stream */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PORT */</span>
<span class="n">obj_t</span> <span class="n">name</span><span class="p">;</span> <span class="cm">/* name of stream */</span>
<span class="kt">FILE</span> <span class="o">*</span><span class="n">stream</span><span class="p">;</span>
<span class="p">}</span> <span class="n">port_s</span><span class="p">;</span>
</pre></div>
@ -84,14 +84,14 @@ <h3>Navigation</h3>
<p>Any block in an <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically managed</em></a> <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> can be registered for finalization by calling
<a class="reference internal" href="../topic/finalization.html#mps_finalize" title="mps_finalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_finalize()</span></tt></a>. In the toy Scheme interpreter, this can be done
in <tt class="docutils literal"><span class="pre">make_port</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre> <span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">make_port</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">name</span><span class="p">,</span> <span class="kt">FILE</span> <span class="o">*</span><span class="n">stream</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre> <span class="k">static</span> <span class="n">obj_t</span> <span class="nf">make_port</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">name</span><span class="p">,</span> <span class="kt">FILE</span> <span class="o">*</span><span class="n">stream</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">port_ref</span><span class="p">;</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">port_ref</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">port_s</span><span class="p">));</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory in make_port&quot;</span><span class="p">);</span>
<span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">port</span><span class="p">.</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_PORT</span><span class="p">;</span>
@ -127,17 +127,17 @@ <h3>Navigation</h3>
message queue is at the start of the read–eval–print loop. When a
finalization message is found, the associated file handle is closed
(unless it has been closed already), and the message is discarded.</p>
<div class="highlight-c"><div class="highlight"><pre> <span class="kt">mps_message_type_t</span> <span class="n">type</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre> <span class="n">mps_message_type_t</span> <span class="n">type</span><span class="p">;</span>
<span class="k">while</span> <span class="p">(</span><span class="n">mps_message_queue_type</span><span class="p">(</span><span class="o">&amp;</span><span class="n">type</span><span class="p">,</span> <span class="n">arena</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">mps_message_t</span> <span class="n">message</span><span class="p">;</span>
<span class="kt">mps_bool_t</span> <span class="n">b</span><span class="p">;</span>
<span class="n">mps_message_t</span> <span class="n">message</span><span class="p">;</span>
<span class="n">mps_bool_t</span> <span class="n">b</span><span class="p">;</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">mps_message_get</span><span class="p">(</span><span class="o">&amp;</span><span class="n">message</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">type</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">b</span><span class="p">);</span> <span class="cm">/* we just checked there was one */</span>
<span class="hll"> <span class="k">if</span> <span class="p">(</span><span class="n">type</span> <span class="o">==</span> <span class="n">mps_message_type_finalization</span><span class="p">())</span> <span class="p">{</span>
</span> <span class="kt">mps_addr_t</span> <span class="n">port_ref</span><span class="p">;</span>
<span class="kt">obj_t</span> <span class="n">port</span><span class="p">;</span>
</span> <span class="n">mps_addr_t</span> <span class="n">port_ref</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">port</span><span class="p">;</span>
<span class="hll"> <span class="n">mps_message_finalization_ref</span><span class="p">(</span><span class="o">&amp;</span><span class="n">port_ref</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">message</span><span class="p">);</span>
</span> <span class="n">port</span> <span class="o">=</span> <span class="n">port_ref</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">port</span><span class="p">)</span> <span class="o">==</span> <span class="n">TYPE_PORT</span><span class="p">);</span>
@ -176,11 +176,11 @@ <h3>Navigation</h3>
optimization: setting <tt class="docutils literal"><span class="pre">stream</span></tt> to <tt class="docutils literal"><span class="pre">NULL</span></tt> ensures that the file
handle wouldn&#8217;t be closed more than once, even if the port object were
later finalized.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">port_close</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">port</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">port_close</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">port</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">assert</span><span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">port</span><span class="p">)</span> <span class="o">==</span> <span class="n">TYPE_PORT</span><span class="p">);</span>
<span class="k">if</span><span class="p">(</span><span class="n">port</span><span class="o">-&gt;</span><span class="n">port</span><span class="p">.</span><span class="n">stream</span> <span class="o">!=</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">port_ref</span> <span class="o">=</span> <span class="n">port</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">port_ref</span> <span class="o">=</span> <span class="n">port</span><span class="p">;</span>
<span class="n">fclose</span><span class="p">(</span><span class="n">port</span><span class="o">-&gt;</span><span class="n">port</span><span class="p">.</span><span class="n">stream</span><span class="p">);</span>
<span class="n">port</span><span class="o">-&gt;</span><span class="n">port</span><span class="p">.</span><span class="n">stream</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="hll"> <span class="n">mps_definalize</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">port_ref</span><span class="p">);</span>
@ -253,24 +253,24 @@ <h3>Navigation</h3>
case of a hash table, it is most convenient to inline it in the hash
table&#8217;s metadata:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">table_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_TABLE */</span>
<span class="kt">hash_t</span> <span class="n">hash</span><span class="p">;</span> <span class="cm">/* hash function */</span>
<span class="kt">cmp_t</span> <span class="n">cmp</span><span class="p">;</span> <span class="cm">/* comparison function */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_TABLE */</span>
<span class="n">hash_t</span> <span class="n">hash</span><span class="p">;</span> <span class="cm">/* hash function */</span>
<span class="n">cmp_t</span> <span class="n">cmp</span><span class="p">;</span> <span class="cm">/* comparison function */</span>
<span class="hll"> <span class="n">mps_ld_s</span> <span class="n">ld</span><span class="p">;</span> <span class="cm">/* location dependency */</span>
</span> <span class="kt">obj_t</span> <span class="n">buckets</span><span class="p">;</span> <span class="cm">/* hash buckets */</span>
</span> <span class="n">obj_t</span> <span class="n">buckets</span><span class="p">;</span> <span class="cm">/* hash buckets */</span>
<span class="p">}</span> <span class="n">table_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Before being used, the location dependency must be reset to indicate
that nothing is depended upon, by calling <a class="reference internal" href="../topic/location.html#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>.</p>
<p>For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">make_table</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">length</span><span class="p">,</span> <span class="kt">hash_t</span> <span class="n">hashf</span><span class="p">,</span> <span class="kt">cmp_t</span> <span class="n">cmpf</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">make_table</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">length</span><span class="p">,</span> <span class="n">hash_t</span> <span class="n">hashf</span><span class="p">,</span> <span class="n">cmp_t</span> <span class="n">cmpf</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">l</span><span class="p">,</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">table_s</span><span class="p">));</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory in make_table&quot;</span><span class="p">);</span>
<span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">table</span><span class="p">.</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_TABLE</span><span class="p">;</span>
@ -296,12 +296,12 @@ <h3>Navigation</h3>
dependency.)</p>
<p>In the toy Scheme interpreter, this is done just before the computation
of the hash of the address.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eq_hash</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eq_hash</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="n">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">union</span> <span class="p">{</span><span class="kt">char</span> <span class="n">s</span><span class="p">[</span><span class="k">sizeof</span><span class="p">(</span><span class="kt">obj_t</span><span class="p">)];</span> <span class="kt">obj_t</span> <span class="n">addr</span><span class="p">;}</span> <span class="n">u</span><span class="p">;</span>
<span class="k">union</span> <span class="p">{</span><span class="kt">char</span> <span class="n">s</span><span class="p">[</span><span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">)];</span> <span class="n">obj_t</span> <span class="n">addr</span><span class="p">;}</span> <span class="n">u</span><span class="p">;</span>
<span class="hll"> <span class="k">if</span> <span class="p">(</span><span class="n">ld</span><span class="p">)</span> <span class="n">mps_ld_add</span><span class="p">(</span><span class="n">ld</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">obj</span><span class="p">);</span>
</span> <span class="n">u</span><span class="p">.</span><span class="n">addr</span> <span class="o">=</span> <span class="n">obj</span><span class="p">;</span>
<span class="k">return</span> <span class="n">hash</span><span class="p">(</span><span class="n">u</span><span class="p">.</span><span class="n">s</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">obj_t</span><span class="p">));</span>
<span class="k">return</span> <span class="n">hash</span><span class="p">(</span><span class="n">u</span><span class="p">.</span><span class="n">s</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
</div>
@ -309,7 +309,7 @@ <h3>Navigation</h3>
avoids adding unnecessary dependencies on a location. For example, an
<tt class="docutils literal"><span class="pre">eqv?</span></tt> hash table does not need to depend on the location of numbers
and characters:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eqv_hash</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eqv_hash</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="n">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">switch</span><span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">obj</span><span class="p">))</span> <span class="p">{</span>
<span class="k">case</span> <span class="n">TYPE_INTEGER</span>:
@ -339,7 +339,7 @@ <h3>Navigation</h3>
function <a class="reference internal" href="../topic/location.html#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> tells you if any of the blocks whose
locations you depended upon since the last call to
<a class="reference internal" href="../topic/location.html#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a> might have moved.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">table_ref</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">key</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">table_ref</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">key</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">struct</span> <span class="n">bucket_s</span> <span class="o">*</span><span class="n">b</span> <span class="o">=</span> <span class="n">buckets_find</span><span class="p">(</span><span class="n">tbl</span><span class="p">,</span> <span class="n">tbl</span><span class="o">-&gt;</span><span class="n">table</span><span class="p">.</span><span class="n">buckets</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">b</span> <span class="o">&amp;&amp;</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">key</span> <span class="o">!=</span> <span class="nb">NULL</span> <span class="o">&amp;&amp;</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">key</span> <span class="o">!=</span> <span class="n">obj_deleted</span><span class="p">)</span>
@ -425,7 +425,7 @@ <h3>Navigation</h3>
<p>Don&#8217;t forget to check the location dependency for staleness if you are
about to delete a key from a hash table but discover that it&#8217;s not
there. In the toy Scheme interpreter, deletion looks like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">table_delete</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">key</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">table_delete</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">key</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">struct</span> <span class="n">bucket_s</span> <span class="o">*</span><span class="n">b</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">tbl</span><span class="p">)</span> <span class="o">==</span> <span class="n">TYPE_TABLE</span><span class="p">);</span>
@ -500,9 +500,9 @@ <h3>Navigation</h3>
and values to have different ranks.</p>
<p>These vectors will be allocated from an AWL pool with two allocation
points, one for strong references, and one for weak references:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_pool_t</span> <span class="n">buckets_pool</span><span class="p">;</span> <span class="cm">/* pool for hash table buckets */</span>
<span class="k">static</span> <span class="kt">mps_ap_t</span> <span class="n">strong_buckets_ap</span><span class="p">;</span> <span class="cm">/* allocation point for strong buckets */</span>
<span class="k">static</span> <span class="kt">mps_ap_t</span> <span class="n">weak_buckets_ap</span><span class="p">;</span> <span class="cm">/* allocation point for weak buckets */</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_pool_t</span> <span class="n">buckets_pool</span><span class="p">;</span> <span class="cm">/* pool for hash table buckets */</span>
<span class="k">static</span> <span class="n">mps_ap_t</span> <span class="n">strong_buckets_ap</span><span class="p">;</span> <span class="cm">/* allocation point for strong buckets */</span>
<span class="k">static</span> <span class="n">mps_ap_t</span> <span class="n">weak_buckets_ap</span><span class="p">;</span> <span class="cm">/* allocation point for weak buckets */</span>
</pre></div>
</div>
<div class="admonition-note admonition">
@ -515,16 +515,16 @@ <h3>Navigation</h3>
replacing it with a null pointer when it is <a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fixed</em></a> by the object
format&#8217;s <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a>. So the scan method for the buckets is
going to have the following structure. (See below for the actual code.)</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">buckets_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">buckets_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">while</span> <span class="p">(</span><span class="n">base</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">length</span> <span class="o">=</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">length</span><span class="p">;</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">length</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">bucket</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="n">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">bucket</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="k">if</span> <span class="p">(</span><span class="n">MPS_FIX1</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="n">p</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="k">return</span> <span class="n">res</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">p</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* TODO: key/value was splatted: splat value/key too */</span>
@ -556,9 +556,9 @@ <h3>Navigation</h3>
<p>The AWL pool determines an object&#8217;s dependent object by calling a
function that you supply when creating the pool. This means that each
object needs to have a reference to its dependent object:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_addr_t</span> <span class="nf">buckets_find_dependent</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_addr_t</span> <span class="nf">buckets_find_dependent</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="k">return</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">dependent</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
@ -580,25 +580,25 @@ <h3>Navigation</h3>
<span class="kt">size_t</span> <span class="n">length</span><span class="p">;</span> <span class="cm">/* number of buckets (tagged) */</span>
<span class="kt">size_t</span> <span class="n">used</span><span class="p">;</span> <span class="cm">/* number of buckets in use (tagged) */</span>
<span class="kt">size_t</span> <span class="n">deleted</span><span class="p">;</span> <span class="cm">/* number of deleted buckets (tagged) */</span>
<span class="kt">obj_t</span> <span class="n">bucket</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> <span class="cm">/* hash buckets */</span>
<span class="p">}</span> <span class="n">buckets_s</span><span class="p">,</span> <span class="o">*</span><span class="kt">buckets_t</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">bucket</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> <span class="cm">/* hash buckets */</span>
<span class="p">}</span> <span class="n">buckets_s</span><span class="p">,</span> <span class="o">*</span><span class="n">buckets_t</span><span class="p">;</span>
</pre></div>
</div>
<p>Now the full details of the scan method can be given, with the revised
code highlighted:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">buckets_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">buckets_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">while</span> <span class="p">(</span><span class="n">base</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="hll"> <span class="kt">size_t</span> <span class="n">i</span><span class="p">,</span> <span class="n">length</span> <span class="o">=</span> <span class="n">UNTAG_SIZE</span><span class="p">(</span><span class="n">buckets</span><span class="o">-&gt;</span><span class="n">length</span><span class="p">);</span>
</span><span class="hll"> <span class="n">FIX</span><span class="p">(</span><span class="n">buckets</span><span class="o">-&gt;</span><span class="n">dependent</span><span class="p">);</span>
</span><span class="hll"> <span class="k">if</span><span class="p">(</span><span class="n">buckets</span><span class="o">-&gt;</span><span class="n">dependent</span> <span class="o">!=</span> <span class="nb">NULL</span><span class="p">)</span>
</span><span class="hll"> <span class="n">assert</span><span class="p">(</span><span class="n">buckets</span><span class="o">-&gt;</span><span class="n">dependent</span><span class="o">-&gt;</span><span class="n">length</span> <span class="o">==</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">length</span><span class="p">);</span>
</span> <span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">length</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">bucket</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="n">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">buckets</span><span class="o">-&gt;</span><span class="n">bucket</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="k">if</span> <span class="p">(</span><span class="n">MPS_FIX1</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="n">p</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="k">return</span> <span class="n">res</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">p</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="hll"> <span class="cm">/* key/value was splatted: splat value/key too */</span>
@ -649,9 +649,9 @@ <h3>Navigation</h3>
</ol>
</div>
<p>The <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a> is straightforward:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_addr_t</span> <span class="nf">buckets_skip</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_addr_t</span> <span class="nf">buckets_skip</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">buckets_t</span> <span class="n">buckets</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">length</span> <span class="o">=</span> <span class="n">UNTAG_SIZE</span><span class="p">(</span><span class="n">buckets</span><span class="o">-&gt;</span><span class="n">length</span><span class="p">);</span>
<span class="k">return</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span><span class="n">base</span> <span class="o">+</span>
<span class="n">ALIGN</span><span class="p">(</span><span class="n">offsetof</span><span class="p">(</span><span class="n">buckets_s</span><span class="p">,</span> <span class="n">bucket</span><span class="p">)</span> <span class="o">+</span>
@ -679,17 +679,21 @@ <h3>Navigation</h3>
<span class="cm">/* Create an Automatic Weak Linked (AWL) pool to manage the hash table</span>
<span class="cm"> buckets. */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">buckets_pool</span><span class="p">,</span>
<span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_awl</span><span class="p">(),</span>
<span class="n">buckets_fmt</span><span class="p">,</span>
<span class="n">buckets_find_dependent</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">buckets_pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_awl</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">buckets_fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_AWL_FIND_DEPENDENT</span><span class="p">,</span>
<span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">addr_method</span> <span class="o">=</span> <span class="n">buckets_find_dependent</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create buckets pool&quot;</span><span class="p">);</span>
<span class="cm">/* Create allocation points for weak and strong buckets. */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">strong_buckets_ap</span><span class="p">,</span> <span class="n">buckets_pool</span><span class="p">,</span> <span class="n">mps_rank_exact</span><span class="p">());</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">strong_buckets_ap</span><span class="p">,</span> <span class="n">buckets_pool</span><span class="p">,</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_RANK</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">rank</span> <span class="o">=</span> <span class="n">mps_rank_exact</span><span class="p">()},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create strong buckets allocation point&quot;</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">weak_buckets_ap</span><span class="p">,</span> <span class="n">buckets_pool</span><span class="p">,</span> <span class="n">mps_rank_weak</span><span class="p">());</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">weak_buckets_ap</span><span class="p">,</span> <span class="n">buckets_pool</span><span class="p">,</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_RANK</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">rank</span> <span class="o">=</span> <span class="n">mps_rank_weak</span><span class="p">()},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create weak buckets allocation point&quot;</span><span class="p">);</span>
</pre></div>
</div>
@ -749,15 +753,15 @@ <h3>Navigation</h3>
</ol>
<p>Here&#8217;s the new symbol structure:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">symbol_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_SYMBOL */</span>
<span class="kt">obj_t</span> <span class="n">name</span><span class="p">;</span> <span class="cm">/* its name (a string) */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_SYMBOL */</span>
<span class="n">obj_t</span> <span class="n">name</span><span class="p">;</span> <span class="cm">/* its name (a string) */</span>
<span class="p">}</span> <span class="n">symbol_s</span><span class="p">;</span>
</pre></div>
</div>
<p>and the new implementation of <tt class="docutils literal"><span class="pre">intern</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">intern_string</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">name</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">intern_string</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">name</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">symbol</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">symbol</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="o">==</span> <span class="n">TYPE_STRING</span><span class="p">);</span>
<span class="n">symbol</span> <span class="o">=</span> <span class="n">table_ref</span><span class="p">(</span><span class="n">symtab</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span>
<span class="k">if</span><span class="p">(</span><span class="n">symbol</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
@ -767,7 +771,7 @@ <h3>Navigation</h3>
<span class="k">return</span> <span class="n">symbol</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">intern</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">string</span><span class="p">)</span>
<span class="k">static</span> <span class="n">obj_t</span> <span class="nf">intern</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">string</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">return</span> <span class="n">intern_string</span><span class="p">(</span><span class="n">make_string</span><span class="p">(</span><span class="n">strlen</span><span class="p">(</span><span class="n">string</span><span class="p">),</span> <span class="n">string</span><span class="p">));</span>
<span class="p">}</span>
@ -775,7 +779,7 @@ <h3>Navigation</h3>
</div>
<p>The symbol table now becomes a very simple <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a>, that only has
to be registered once (not <a class="reference internal" href="lang.html#guide-lang-root"><em>every time it is rehashed</em></a>, as previously):</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_addr_t</span> <span class="n">ref</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_addr_t</span> <span class="n">ref</span><span class="p">;</span>
<span class="n">symtab</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">ref</span> <span class="o">=</span> <span class="o">&amp;</span><span class="n">symtab</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create_table</span><span class="p">(</span><span class="o">&amp;</span><span class="n">symtab_root</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_rank_exact</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span>
@ -823,23 +827,22 @@ <h3>Navigation</h3>
<p>Here the appropriate class is <a class="reference internal" href="../pool/amcz.html#pool-amcz"><em>AMCZ (Automatic Mostly-Copying Zero-rank)</em></a>, and the necessary code
changes are straightforward. First, global variables for the new pool
and its <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_pool_t</span> <span class="n">leaf_pool</span><span class="p">;</span> <span class="cm">/* pool for leaf objects */</span>
<span class="k">static</span> <span class="kt">mps_ap_t</span> <span class="n">leaf_ap</span><span class="p">;</span> <span class="cm">/* allocation point for leaf objects */</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_pool_t</span> <span class="n">leaf_pool</span><span class="p">;</span> <span class="cm">/* pool for leaf objects */</span>
<span class="k">static</span> <span class="n">mps_ap_t</span> <span class="n">leaf_ap</span><span class="p">;</span> <span class="cm">/* allocation point for leaf objects */</span>
</pre></div>
</div>
<p>Second, the leaf objects must be allocated on <tt class="docutils literal"><span class="pre">leaf_ap</span></tt> instead of
<tt class="docutils literal"><span class="pre">obj_ap</span></tt>. And third, the pool and its allocation point must be created:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Create an Automatic Mostly-Copying Zero-rank (AMCZ) pool to</span>
<span class="cm"> manage the leaf objects. */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">leaf_pool</span><span class="p">,</span>
<span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_amcz</span><span class="p">(),</span>
<span class="n">obj_fmt</span><span class="p">,</span>
<span class="n">obj_chain</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">leaf_pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_amcz</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">chain</span> <span class="o">=</span> <span class="n">obj_chain</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">obj_fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create leaf pool&quot;</span><span class="p">);</span>
<span class="cm">/* Create allocation point for leaf objects. */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">leaf_ap</span><span class="p">,</span> <span class="n">leaf_pool</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">leaf_ap</span><span class="p">,</span> <span class="n">leaf_pool</span><span class="p">,</span> <span class="n">mps_args_none</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create leaf objects allocation point&quot;</span><span class="p">);</span>
</pre></div>
</div>

8
mps/manual/html/guide/debug.html
View file

@ -227,13 +227,13 @@ <h3>Navigation</h3>
<span id="guide-debug-size"></span><span id="index-5"></span><h2>4.3. Example: allocating with wrong size<a class="headerlink" href="#example-allocating-with-wrong-size" title="Permalink to this headline"></a></h2>
<p>Here&#8217;s another kind of mistake: an off-by-one error in <tt class="docutils literal"><span class="pre">make_string</span></tt>
leading to the allocation of string objects with the wrong size:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">make_string</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">length</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">string</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">make_string</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">length</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">string</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="hll"> <span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="n">offsetof</span><span class="p">(</span><span class="n">string_s</span><span class="p">,</span> <span class="n">string</span><span class="p">)</span> <span class="o">+</span> <span class="n">length</span><span class="cm">/* oops, forgot: +1 */</span><span class="p">);</span>
</span> <span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory in make_string&quot;</span><span class="p">);</span>
<span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">string</span><span class="p">.</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_STRING</span><span class="p">;</span>

151
mps/manual/html/guide/lang.html
View file

@ -90,7 +90,7 @@ <h3>Navigation</h3>
<p>A Scheme object (whose type is not necessarily known) is represented by
an <tt class="docutils literal"><span class="pre">obj_t</span></tt>, which is a pointer to a union of every type in the
language:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">union</span> <span class="n">obj_u</span> <span class="o">*</span><span class="kt">obj_t</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">union</span> <span class="n">obj_u</span> <span class="o">*</span><span class="n">obj_t</span><span class="p">;</span>
<span class="k">typedef</span> <span class="k">union</span> <span class="n">obj_u</span> <span class="p">{</span>
<span class="n">type_s</span> <span class="n">type</span><span class="p">;</span>
<span class="n">pair_s</span> <span class="n">pair</span><span class="p">;</span>
@ -113,8 +113,8 @@ <h3>Navigation</h3>
represented by a pointer to the structure <tt class="docutils literal"><span class="pre">pair_s</span></tt> defined as
follows:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">pair_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PAIR */</span>
<span class="kt">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="n">cdr</span><span class="p">;</span> <span class="cm">/* first and second projections */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PAIR */</span>
<span class="n">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="n">cdr</span><span class="p">;</span> <span class="cm">/* first and second projections */</span>
<span class="p">}</span> <span class="n">pair_s</span><span class="p">;</span>
</pre></div>
</div>
@ -122,7 +122,7 @@ <h3>Navigation</h3>
operate on objects generically, testing <tt class="docutils literal"><span class="pre">TYPE(obj)</span></tt> as necessary
(which is a macro for <tt class="docutils literal"><span class="pre">obj-&gt;type.type</span></tt>). For example, the
<tt class="docutils literal"><span class="pre">print()</span></tt> function is implemented like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">print</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">depth</span><span class="p">,</span> <span class="kt">FILE</span> <span class="o">*</span><span class="n">stream</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">print</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">depth</span><span class="p">,</span> <span class="kt">FILE</span> <span class="o">*</span><span class="n">stream</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">switch</span> <span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">obj</span><span class="p">))</span> <span class="p">{</span>
<span class="k">case</span> <span class="n">TYPE_INTEGER</span>:
@ -140,9 +140,9 @@ <h3>Navigation</h3>
</div>
<p>Each constructor allocates memory for the new object by calling
<tt class="docutils literal"><span class="pre">malloc</span></tt>. For example, <tt class="docutils literal"><span class="pre">make_pair</span></tt> is the constructor for pairs:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">make_pair</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">cdr</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">make_pair</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">cdr</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="p">(</span><span class="kt">obj_t</span><span class="p">)</span><span class="n">malloc</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">pair_s</span><span class="p">));</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="p">(</span><span class="n">obj_t</span><span class="p">)</span><span class="n">malloc</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">pair_s</span><span class="p">));</span>
<span class="k">if</span> <span class="p">(</span><span class="n">obj</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory&quot;</span><span class="p">);</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">pair</span><span class="p">.</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_PAIR</span><span class="p">;</span>
<span class="n">CAR</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="o">=</span> <span class="n">car</span><span class="p">;</span>
@ -181,26 +181,34 @@ <h3>Navigation</h3>
<p>There&#8217;s only one arena, and many MPS functions take an arena as an
argument, so it makes sense for the arena to be a global variable
rather than having to pass it around everywhere:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">;</span>
</pre></div>
</div>
<p>Create an arena by calling <a class="reference internal" href="../topic/arena.html#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>. This function
takes a third argument when creating a virtual memory arena: the size of
the amount of virtual virtual <a class="reference internal" href="../glossary/a.html#term-address-space"><em class="xref std std-term">address space</em></a> (<em>not</em> <a class="reference internal" href="../glossary/r.html#term-ram"><em class="xref std std-term">RAM</em></a>),
in bytes, that the arena will reserve initially. The MPS will ask for
<p>Create an arena by calling <a class="reference internal" href="../topic/arena.html#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a>. This function
takes a <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a> when creating a virtual memory arena:
the size of virtual <a class="reference internal" href="../glossary/a.html#term-address-space"><em class="xref std std-term">address space</em></a> (<em>not</em> <a class="reference internal" href="../glossary/r.html#term-ram"><em class="xref std std-term">RAM</em></a>), in
bytes, that the arena will reserve initially. The MPS will ask for
more address space if it runs out, but the more times it has to extend
its address space, the less efficient garbage collection will become.
The MPS works best if you reserve an address space that is several times
larger than your peak memory usage.</p>
The MPS works best if you reserve an address space that is several
times larger than your peak memory usage.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">Functions in the MPS interface take <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a> for
arguments that are optional, or are only required in some
circumstances. These argument are passed in the form of an array
of structures of type <a class="reference internal" href="../topic/keyword.html#mps_arg_s" title="mps_arg_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_arg_s</span></tt></a>. See
<a class="reference internal" href="../topic/keyword.html#topic-keyword"><em>Keyword arguments</em></a> for the full details.</p>
</div>
<p>Let&#8217;s reserve 32 megabytes:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span>
<span class="n">mps_arena_class_vm</span><span class="p">(),</span>
<span class="p">(</span><span class="kt">size_t</span><span class="p">)(</span><span class="mi">32</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">));</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_vm</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">32</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create arena&quot;</span><span class="p">);</span>
</pre></div>
</div>
<p><a class="reference internal" href="../topic/arena.html#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> is typical of functions in the MPS
<p><a class="reference internal" href="../topic/arena.html#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> is typical of functions in the MPS
interface in that it stores its result in a location pointed to by an
<a class="reference internal" href="../glossary/o.html#term-out-parameter"><em class="xref std std-term">out parameter</em></a> (here, <tt class="docutils literal"><span class="pre">&amp;arena</span></tt>) and returns a <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result
code</em></a>, which is <a class="reference internal" href="../topic/error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the function succeeded, or
@ -266,7 +274,7 @@ <h3>Navigation</h3>
<span class="n">obj_pad</span><span class="p">,</span>
<span class="p">};</span>
<span class="kt">mps_fmt_t</span> <span class="n">obj_fmt</span><span class="p">;</span>
<span class="n">mps_fmt_t</span> <span class="n">obj_fmt</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_fmt_create_A</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_fmt</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">obj_fmt_s</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj format&quot;</span><span class="p">);</span>
</pre></div>
@ -324,11 +332,11 @@ <h3>Navigation</h3>
discover references and so determine which objects are <a class="reference internal" href="../glossary/l.html#term-live"><em class="xref std std-term">alive</em></a> and which are <a class="reference internal" href="../glossary/d.html#term-dead"><em class="xref std std-term">dead</em></a>, and also to update references
after objects have been moved.</p>
<p>Here&#8217;s the scan method for the toy Scheme interpreter:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">while</span> <span class="p">(</span><span class="n">base</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="k">switch</span> <span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">obj</span><span class="p">))</span> <span class="p">{</span>
<span class="k">case</span> <span class="n">TYPE_PAIR</span>:
<span class="n">FIX</span><span class="p">(</span><span class="n">CAR</span><span class="p">(</span><span class="n">obj</span><span class="p">));</span>
@ -406,9 +414,9 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/format.html#mps_fmt_skip_t" title="mps_fmt_skip_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_skip_t</span></tt></a>. It is called by the MPS to skip over an
object belonging to the format, and also to determine its size.</p>
<p>Here&#8217;s the skip method for the toy Scheme interpreter:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_addr_t</span> <span class="nf">obj_skip</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_addr_t</span> <span class="nf">obj_skip</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="k">switch</span> <span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">obj</span><span class="p">))</span> <span class="p">{</span>
<span class="k">case</span> <span class="n">TYPE_PAIR</span>:
<span class="n">base</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span><span class="n">base</span> <span class="o">+</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">pair_s</span><span class="p">));</span>
@ -461,24 +469,24 @@ <h3>Navigation</h3>
The first type is suitable for forwarding objects of three words or
longer:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">fwd_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_FWD */</span>
<span class="kt">obj_t</span> <span class="n">fwd</span><span class="p">;</span> <span class="cm">/* forwarded object */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_FWD */</span>
<span class="n">obj_t</span> <span class="n">fwd</span><span class="p">;</span> <span class="cm">/* forwarded object */</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">;</span> <span class="cm">/* total size of this object */</span>
<span class="p">}</span> <span class="n">fwd_s</span><span class="p">;</span>
</pre></div>
</div>
<p>while the second type is suitable for forwarding objects of two words:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">fwd2_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_FWD2 */</span>
<span class="kt">obj_t</span> <span class="n">fwd</span><span class="p">;</span> <span class="cm">/* forwarded object */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_FWD2 */</span>
<span class="n">obj_t</span> <span class="n">fwd</span><span class="p">;</span> <span class="cm">/* forwarded object */</span>
<span class="p">}</span> <span class="n">fwd2_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Here&#8217;s the forward method for the toy Scheme interpreter:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">obj_fwd</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">old</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">new</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">obj_fwd</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">old</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">new</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">old</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">limit</span> <span class="o">=</span> <span class="n">obj_skip</span><span class="p">(</span><span class="n">old</span><span class="p">);</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">old</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">limit</span> <span class="o">=</span> <span class="n">obj_skip</span><span class="p">(</span><span class="n">old</span><span class="p">);</span>
<span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span><span class="n">limit</span> <span class="o">-</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span><span class="n">old</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="n">size</span> <span class="o">&gt;=</span> <span class="n">ALIGN_UP</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">fwd2_s</span><span class="p">)));</span>
<span class="k">if</span> <span class="p">(</span><span class="n">size</span> <span class="o">==</span> <span class="n">ALIGN_UP</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">fwd2_s</span><span class="p">)))</span> <span class="p">{</span>
@ -537,9 +545,9 @@ <h3>Navigation</h3>
object is a <a class="reference internal" href="../glossary/f.html#term-forwarding-object"><em class="xref std std-term">forwarding object</em></a>, and if it is, to determine the
location where that object was moved.</p>
<p>Here&#8217;s the is-forwarded method for the toy Scheme interpreter:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_addr_t</span> <span class="nf">obj_isfwd</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_addr_t</span> <span class="nf">obj_isfwd</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="k">switch</span> <span class="p">(</span><span class="n">TYPE</span><span class="p">(</span><span class="n">obj</span><span class="p">))</span> <span class="p">{</span>
<span class="k">case</span> <span class="n">TYPE_FWD2</span>:
<span class="k">return</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">fwd2</span><span class="p">.</span><span class="n">fwd</span><span class="p">;</span>
@ -573,7 +581,7 @@ <h3>Navigation</h3>
types of padding object. The first type is suitable for padding
objects of two words or longer:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">pad_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PAD */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PAD */</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">;</span> <span class="cm">/* total size of this object */</span>
<span class="p">}</span> <span class="n">pad_s</span><span class="p">;</span>
</pre></div>
@ -581,14 +589,14 @@ <h3>Navigation</h3>
<p>while the second type is suitable for padding objects consisting of a
single word:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">pad1_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PAD1 */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_PAD1 */</span>
<span class="p">}</span> <span class="n">pad1_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Here&#8217;s the padding method:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">obj_pad</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">obj_pad</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">assert</span><span class="p">(</span><span class="n">size</span> <span class="o">&gt;=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">pad1_s</span><span class="p">)));</span>
<span class="k">if</span> <span class="p">(</span><span class="n">size</span> <span class="o">==</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">pad1_s</span><span class="p">)))</span> <span class="p">{</span>
<span class="n">TYPE</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="o">=</span> <span class="n">TYPE_PAD1</span><span class="p">;</span>
@ -664,7 +672,7 @@ <h3>Navigation</h3>
</div>
<p>Second, the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">mps_fmt_A_s</span> <span class="n">obj_fmt_s</span> <span class="o">=</span> <span class="p">{</span>
<span class="k">sizeof</span><span class="p">(</span><span class="kt">mps_word_t</span><span class="p">),</span>
<span class="k">sizeof</span><span class="p">(</span><span class="n">mps_word_t</span><span class="p">),</span>
<span class="n">obj_scan</span><span class="p">,</span>
<span class="n">obj_skip</span><span class="p">,</span>
<span class="nb">NULL</span><span class="p">,</span>
@ -673,7 +681,7 @@ <h3>Navigation</h3>
<span class="n">obj_pad</span><span class="p">,</span>
<span class="p">};</span>
<span class="kt">mps_fmt_t</span> <span class="n">obj_fmt</span><span class="p">;</span>
<span class="n">mps_fmt_t</span> <span class="n">obj_fmt</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_fmt_create_A</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_fmt</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">obj_fmt_s</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj format&quot;</span><span class="p">);</span>
</pre></div>
@ -684,7 +692,7 @@ <h3>Navigation</h3>
<span class="p">{</span> <span class="mi">170</span><span class="p">,</span> <span class="mf">0.45</span> <span class="p">},</span>
<span class="p">};</span>
<span class="kt">mps_chain_t</span> <span class="n">obj_chain</span><span class="p">;</span>
<span class="n">mps_chain_t</span> <span class="n">obj_chain</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_chain_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_chain</span><span class="p">,</span>
<span class="n">arena</span><span class="p">,</span>
<span class="n">LENGTH</span><span class="p">(</span><span class="n">obj_gen_params</span><span class="p">),</span>
@ -693,12 +701,11 @@ <h3>Navigation</h3>
</pre></div>
</div>
<p>And finally the <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_pool_t</span> <span class="n">obj_pool</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_pool</span><span class="p">,</span>
<span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_amc</span><span class="p">(),</span>
<span class="n">obj_fmt</span><span class="p">,</span>
<span class="n">obj_chain</span><span class="p">);</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_pool_t</span> <span class="n">obj_pool</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_amc</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">chain</span> <span class="o">=</span> <span class="n">obj_chain</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">obj_fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj pool&quot;</span><span class="p">);</span>
</pre></div>
</div>
@ -721,15 +728,15 @@ <h3>Navigation</h3>
describe to the MPS how to <a class="reference internal" href="../glossary/s.html#term-scan"><em class="xref std std-term">scan</em></a> them for references.</p>
<p>The toy Scheme interpreter has a number of static variables that point
to heap-allocated objects. First, the special objects, including:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="n">obj_empty</span><span class="p">;</span> <span class="cm">/* (), the empty list */</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="n">obj_empty</span><span class="p">;</span> <span class="cm">/* (), the empty list */</span>
</pre></div>
</div>
<p>Second, the predefined symbols, including:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="n">obj_quote</span><span class="p">;</span> <span class="cm">/* &quot;quote&quot; symbol */</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="n">obj_quote</span><span class="p">;</span> <span class="cm">/* &quot;quote&quot; symbol */</span>
</pre></div>
</div>
<p>And third, the global symbol table:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="o">*</span><span class="n">symtab</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="o">*</span><span class="n">symtab</span><span class="p">;</span>
<span class="k">static</span> <span class="kt">size_t</span> <span class="n">symtab_size</span><span class="p">;</span>
</pre></div>
</div>
@ -740,7 +747,7 @@ <h3>Navigation</h3>
<p>In the case of the toy Scheme interpreter, the root scanning function
for the special objects and the predefined symbols could be written
like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">globals_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">s</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">globals_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">s</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="n">FIX</span><span class="p">(</span><span class="n">obj_empty</span><span class="p">);</span>
@ -755,7 +762,7 @@ <h3>Navigation</h3>
<p>but in fact the interpreter already has tables of these global
objects, so it&#8217;s simpler and more extensible for the root scanning
function to iterate over them:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">globals_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">s</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">globals_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">s</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">size_t</span> <span class="n">i</span><span class="p">;</span>
@ -770,7 +777,7 @@ <h3>Navigation</h3>
</div>
<p>Each root scanning function must be registered with the MPS by calling
<a class="reference internal" href="../topic/root.html#mps_root_create" title="mps_root_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create()</span></tt></a>, like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_root_t</span> <span class="n">globals_root</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_root_t</span> <span class="n">globals_root</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">globals_root</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_rank_exact</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span>
<span class="n">globals_scan</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t register globals root&quot;</span><span class="p">);</span>
@ -808,11 +815,11 @@ <h3>Navigation</h3>
the global symbol table, but the case of a table of references is
sufficiently common that the MPS provides a convenient (and optimized)
function, <a class="reference internal" href="../topic/root.html#mps_root_create_table" title="mps_root_create_table"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_table()</span></tt></a>, for registering it:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_root_t</span> <span class="n">symtab_root</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_root_t</span> <span class="n">symtab_root</span><span class="p">;</span>
<span class="cm">/* ... */</span>
<span class="kt">mps_addr_t</span> <span class="n">ref</span> <span class="o">=</span> <span class="n">symtab</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">ref</span> <span class="o">=</span> <span class="n">symtab</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create_table</span><span class="p">(</span><span class="o">&amp;</span><span class="n">symtab_root</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_rank_exact</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span>
<span class="n">ref</span><span class="p">,</span> <span class="n">symtab_size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t register new symtab root&quot;</span><span class="p">);</span>
@ -821,15 +828,15 @@ <h3>Navigation</h3>
<p id="guide-lang-roots-rehash">The root must be re-registered whenever the global symbol table
changes size:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">rehash</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">obj_t</span> <span class="o">*</span><span class="n">old_symtab</span> <span class="o">=</span> <span class="n">symtab</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="o">*</span><span class="n">old_symtab</span> <span class="o">=</span> <span class="n">symtab</span><span class="p">;</span>
<span class="kt">unsigned</span> <span class="n">old_symtab_size</span> <span class="o">=</span> <span class="n">symtab_size</span><span class="p">;</span>
<span class="kt">mps_root_t</span> <span class="n">old_symtab_root</span> <span class="o">=</span> <span class="n">symtab_root</span><span class="p">;</span>
<span class="n">mps_root_t</span> <span class="n">old_symtab_root</span> <span class="o">=</span> <span class="n">symtab_root</span><span class="p">;</span>
<span class="kt">unsigned</span> <span class="n">i</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">ref</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">ref</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">symtab_size</span> <span class="o">*=</span> <span class="mi">2</span><span class="p">;</span>
<span class="n">symtab</span> <span class="o">=</span> <span class="n">malloc</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="kt">obj_t</span><span class="p">)</span> <span class="o">*</span> <span class="n">symtab_size</span><span class="p">);</span>
<span class="n">symtab</span> <span class="o">=</span> <span class="n">malloc</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">)</span> <span class="o">*</span> <span class="n">symtab_size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">symtab</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory&quot;</span><span class="p">);</span>
<span class="cm">/* Initialize the new table to NULL so that &quot;find&quot; will work. */</span>
@ -843,7 +850,7 @@ <h3>Navigation</h3>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">old_symtab_size</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
<span class="k">if</span> <span class="p">(</span><span class="n">old_symtab</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">!=</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">obj_t</span> <span class="o">*</span><span class="n">where</span> <span class="o">=</span> <span class="n">find</span><span class="p">(</span><span class="n">old_symtab</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-&gt;</span><span class="n">symbol</span><span class="p">.</span><span class="n">string</span><span class="p">);</span>
<span class="n">obj_t</span> <span class="o">*</span><span class="n">where</span> <span class="o">=</span> <span class="n">find</span><span class="p">(</span><span class="n">old_symtab</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-&gt;</span><span class="n">symbol</span><span class="p">.</span><span class="n">string</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">where</span> <span class="o">!=</span> <span class="nb">NULL</span><span class="p">);</span> <span class="cm">/* new table shouldn&#39;t be full */</span>
<span class="n">assert</span><span class="p">(</span><span class="o">*</span><span class="n">where</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">);</span> <span class="cm">/* shouldn&#39;t be in new table */</span>
<span class="o">*</span><span class="n">where</span> <span class="o">=</span> <span class="n">old_symtab</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
@ -906,7 +913,7 @@ <h3>Navigation</h3>
</ol>
<p>You register a thread with an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> by calling
<a class="reference internal" href="../topic/thread.html#mps_thread_reg" title="mps_thread_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_thread_reg()</span></tt></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_thr_t</span> <span class="kr">thread</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_thr_t</span> <span class="kr">thread</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_thread_reg</span><span class="p">(</span><span class="o">&amp;</span><span class="kr">thread</span><span class="p">,</span> <span class="n">arena</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t register thread&quot;</span><span class="p">);</span>
</pre></div>
@ -915,7 +922,7 @@ <h3>Navigation</h3>
calling <a class="reference internal" href="../topic/root.html#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a> and passing
<a class="reference internal" href="../topic/root.html#mps_stack_scan_ambig" title="mps_stack_scan_ambig"><tt class="xref c c-func docutils literal"><span class="pre">mps_stack_scan_ambig()</span></tt></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="n">marker</span> <span class="o">=</span> <span class="o">&amp;</span><span class="n">marker</span><span class="p">;</span>
<span class="kt">mps_root_t</span> <span class="n">reg_root</span><span class="p">;</span>
<span class="n">mps_root_t</span> <span class="n">reg_root</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create_reg</span><span class="p">(</span><span class="o">&amp;</span><span class="n">reg_root</span><span class="p">,</span>
<span class="n">arena</span><span class="p">,</span>
<span class="n">mps_rank_ambig</span><span class="p">(),</span>
@ -946,11 +953,11 @@ <h3>Navigation</h3>
<p><a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">Manual</em></a> pools typically support
<a class="reference internal" href="../glossary/m.html#term-malloc"><em class="xref std std-term">malloc</em></a>-like allocation using the function
<a class="reference internal" href="../topic/allocation.html#mps_alloc" title="mps_alloc"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc()</span></tt></a>. But <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatic</em></a> pools cannot, because of the following problem:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">make_pair</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">cdr</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">make_pair</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">cdr</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_alloc</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">pool</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">pair_s</span><span class="p">));</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory in make_pair&quot;</span><span class="p">);</span>
<span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
@ -972,23 +979,23 @@ <h3>Navigation</h3>
<p>The MPS solves this problem via the fast, nearly lock-free
<a class="reference internal" href="../topic/allocation.html#topic-allocation-point-protocol"><em>Allocation point protocol</em></a>. This needs an additional
structure, an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a>, to be attached to the pool by
calling <a class="reference internal" href="../topic/allocation.html#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_ap_t</span> <span class="n">obj_ap</span><span class="p">;</span>
calling <a class="reference internal" href="../topic/allocation.html#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_ap_t</span> <span class="n">obj_ap</span><span class="p">;</span>
<span class="cm">/* ... */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_ap</span><span class="p">,</span> <span class="n">obj_pool</span><span class="p">,</span> <span class="n">mps_rank_exact</span><span class="p">());</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_ap</span><span class="p">,</span> <span class="n">obj_pool</span><span class="p">,</span> <span class="n">mps_args_none</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj allocation point&quot;</span><span class="p">);</span>
</pre></div>
</div>
<p>And then the constructor can be implemented like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">make_pair</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">cdr</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">make_pair</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">car</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">cdr</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">pair_s</span><span class="p">));</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">obj_ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory in make_pair&quot;</span><span class="p">);</span>
<span class="n">obj</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">pair</span><span class="p">.</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_PAIR</span><span class="p">;</span>

37
mps/manual/html/index.html
View file

@ -63,24 +63,25 @@ <h1>Memory Pool System<a class="headerlink" href="#memory-pool-system" title="Pe
</li>
<li class="toctree-l1"><a class="reference internal" href="topic/index.html">Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="topic/interface.html">1. Interface conventions</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/error.html">2. Error handing</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/arena.html">3. Arenas</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/pool.html">4. Pools</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/allocation.html">5. Allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/format.html">6. Object formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/scanning.html">7. Scanning</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/thread.html">8. Threads</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/root.html">9. Roots</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/collection.html">10. Garbage collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/message.html">11. Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/finalization.html">12. Finalization</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/location.html">13. Location dependency</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/cache.html">14. Segregated allocation caches</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/pattern.html">15. Allocation patterns</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/frame.html">16. Allocation frames</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/debugging.html">17. Debugging pools</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/telemetry.html">18. Telemetry</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/weak.html">19. Weak references</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/keyword.html">2. Keyword arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/error.html">3. Error handing</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/arena.html">4. Arenas</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/pool.html">5. Pools</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/allocation.html">6. Allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/format.html">7. Object formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/scanning.html">8. Scanning</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/thread.html">9. Threads</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/root.html">10. Roots</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/collection.html">11. Garbage collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/message.html">12. Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/finalization.html">13. Finalization</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/location.html">14. Location dependency</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/cache.html">15. Segregated allocation caches</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/pattern.html">16. Allocation patterns</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/frame.html">17. Allocation frames</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/debugging.html">18. Debugging pools</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/telemetry.html">19. Telemetry</a></li>
<li class="toctree-l2"><a class="reference internal" href="topic/weak.html">20. Weak references</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="pool/index.html">Pool reference</a><ul>

4
mps/manual/html/mmref/bib.html
View file

@ -131,6 +131,10 @@ <h3>Navigation</h3>
</li>
<li><p id="brooksby02">Richard Brooksby. 2002. &#8220;<a class="reference external" href="http://www.ravenbrook.com/project/mps/doc/2002-01-30/ismm2002-paper/">The Memory Pool System: Thirty person-years of memory management development goes Open Source</a>&#8221;. ISMM&#8216;02.</p>
</li>
<li><p id="c1990">International Standard ISO/IEC 9899:1990. &#8220;Programming languages — C&#8221;.</p>
</li>
<li><p id="c1999">International Standard ISO/IEC 9899:1999. &#8220;<a class="reference external" href="http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf">Programming languages — C</a>&#8221;.</p>
</li>
<li><p id="cgz94">Brad Calder, Dirk Grunwald, Benjamin Zorn. 1994. &#8220;<a class="reference external" href="http://cseclassic.ucsd.edu/users/calder/papers/JplVersion.pdf">Quantifying Behavioral Differences Between C and C++ Programs</a>&#8221;. <em>Journal of Programming Languages.</em> 2(4):313&#8211;351.</p>
</li>
<li><p id="cpc00">Dante J. Cannarozzi, Michael P. Plezbert, Ron K. Cytron. 2000. &#8220;<a class="reference external" href="http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.58.9649&amp;rep=rep1&amp;type=pdf">Contaminated garbage collection</a>&#8221;. ACM. Proceedings of the ACM SIGPLAN &#8216;00 conference on on Programming language design and implementation, pp. 264&#8211;273.</p>

2
mps/manual/html/mmref/lang.html
View file

@ -125,7 +125,7 @@ <h3>Navigation</h3>
</div>
<div class="admonition-related-publication admonition">
<p class="first admonition-title">Related publications</p>
<p class="last"><a class="reference internal" href="bib.html#bw88"><em>Boehm &amp; Weiser (1988)</em></a>, <a class="reference internal" href="bib.html#daconta93"><em>Daconta (1993)</em></a>, <a class="reference internal" href="bib.html#zorn93"><em>Zorn (1993)</em></a>.</p>
<p class="last"><a class="reference internal" href="bib.html#c1990"><em>ISO/IEC 9899:1990</em></a>, <a class="reference internal" href="bib.html#c1999"><em>ISO/IEC 9899:1999</em></a>, <a class="reference internal" href="bib.html#bw88"><em>Boehm &amp; Weiser (1988)</em></a>, <a class="reference internal" href="bib.html#daconta93"><em>Daconta (1993)</em></a>, <a class="reference internal" href="bib.html#zorn93"><em>Zorn (1993)</em></a>.</p>
</div>
<div class="admonition-related-link last admonition">
<p class="first admonition-title">Related links</p>

BIN
mps/manual/html/objects.inv
View file

Binary file not shown.

41
mps/manual/html/pool/amc.html
View file

@ -115,19 +115,38 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_amc</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_amc" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an AMC (Automatic
Mostly-Copying) <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an AMC pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_amc</span><span class="p">(),</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="kt">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
<p>When creating an AMC pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
two <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.format</span></tt>; type
<a class="reference internal" href="../topic/format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the
objects allocated in the pool. The format must provide a
<a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a>, a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, a <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward
method</em></a>, an <a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding
method</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_CHAIN</span></tt> (member <tt class="docutils literal"><span class="pre">.val.chain</span></tt>; type
<a class="reference internal" href="../topic/collection.html#mps_chain_t" title="mps_chain_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_chain_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a>
for the pool.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_amc</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">chain</span> <span class="o">=</span> <span class="n">chain</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan
method</em></a>, a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, a <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a>, an
<a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">chain</span></tt> specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a> for the pool.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format and
chain like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_amc</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>

40
mps/manual/html/pool/amcz.html
View file

@ -87,19 +87,37 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_amcz</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_amcz" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an AMCZ (Automatic
Mostly-Copying Zero-rank) <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an AMCZ pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_amcz</span><span class="p">(),</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="kt">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
<p>When creating an AMCZ pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
two <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.format</span></tt>; type
<a class="reference internal" href="../topic/format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the
objects allocated in the pool. The format must provide a
<a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, a <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a>, an
<a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_CHAIN</span></tt> (member <tt class="docutils literal"><span class="pre">.val.chain</span></tt>; type
<a class="reference internal" href="../topic/collection.html#mps_chain_t" title="mps_chain_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_chain_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a>
for the pool.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_amcz</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">chain</span> <span class="o">=</span> <span class="n">chain</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip
method</em></a>, a <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a>, an <a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a>
and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">chain</span></tt> specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a> for the pool.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format and
chain like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_amcz</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>

63
mps/manual/html/pool/ams.html
View file

@ -118,19 +118,36 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_ams</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_ams" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an AMS (Automatic Mark &amp; Sweep)
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an AMS pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_ams</span><span class="p">(),</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="kt">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
<p>When creating an AMS pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
two <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.format</span></tt>; type
<a class="reference internal" href="../topic/format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the
objects allocated in the pool. The format must provide a
<a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> and a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_CHAIN</span></tt> (member <tt class="docutils literal"><span class="pre">.val.chain</span></tt>; type
<a class="reference internal" href="../topic/collection.html#mps_chain_t" title="mps_chain_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_chain_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a>
for the pool. It must have a single generation.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_ams</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">chain</span> <span class="o">=</span> <span class="n">chain</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan
method</em></a> and a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">chain</span></tt> specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a> for the pool. It
must have a single generation.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format and
chain like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_ams</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="function">
@ -138,18 +155,24 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_ams_debug</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_ams_debug" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../topic/debugging.html#topic-debugging"><em>debugging</em></a> version of the AMS pool
class.</p>
<p>When creating a debugging AMS pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>
takes three extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_ams_debug</span><span class="p">(),</span>
<p>When creating a debugging AMS pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt>
requires three keyword arguments: <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> and
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_CHAIN</span></tt> are as described above, and
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_POOL_DEBUG_OPTIONS</span></tt> specifies the debugging
options. See <tt class="xref c c-type docutils literal"><span class="pre">mps_debug_option_s</span></tt>.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format,
chain, and debugging options like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_ams_debug</span><span class="p">(),</span>
<span class="n">mps_debug_option_s</span> <span class="n">debug_option</span><span class="p">,</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="kt">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">debug_option</span></tt> specifies the debugging options. See
<tt class="xref c c-type docutils literal"><span class="pre">mps_debug_option_s</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> and <tt class="docutils literal"><span class="pre">chain</span></tt> are the same as for <a class="reference internal" href="#mps_class_ams" title="mps_class_ams"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_ams()</span></tt></a>.</p>
</div>
</dd></dl>
</div>

95
mps/manual/html/pool/awl.html
View file

@ -93,8 +93,8 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/root.html#mps_rank_exact" title="mps_rank_exact"><tt class="xref c c-func docutils literal"><span class="pre">mps_rank_exact()</span></tt></a> (to allocate ordinary objects containing
<a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact references</em></a>), or <a class="reference internal" href="../topic/root.html#mps_rank_weak" title="mps_rank_weak"><tt class="xref c c-func docutils literal"><span class="pre">mps_rank_weak()</span></tt></a> (to allocate
objects that contain weak references). For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_ap_t</span> <span class="n">ap</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_ap_t</span> <span class="n">ap</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ap</span><span class="p">,</span> <span class="n">pool</span><span class="p">,</span> <span class="n">mps_rank_weak</span><span class="p">());</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;can&#39;t create allocation point&quot;</span><span class="p">);</span>
</pre></div>
@ -169,31 +169,31 @@ <h3>Navigation</h3>
out for the splatting of a reference, and when this is detected, it
splats the corresponding reference in the dependent object.</p>
<p>For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">obj_t</span> <span class="n">obj_deleted</span><span class="p">;</span> <span class="cm">/* deleted entry in hash table */</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">obj_t</span> <span class="n">obj_deleted</span><span class="p">;</span> <span class="cm">/* deleted entry in hash table */</span>
<span class="k">typedef</span> <span class="k">struct</span> <span class="n">weak_array_s</span> <span class="p">{</span>
<span class="k">struct</span> <span class="n">weak_array_s</span> <span class="o">*</span><span class="n">dependent</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">length</span><span class="p">;</span> <span class="cm">/* tagged as &quot;length * 2 + 1&quot; */</span>
<span class="kt">obj_t</span> <span class="n">slot</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span>
<span class="p">}</span> <span class="n">weak_array_s</span><span class="p">,</span> <span class="o">*</span><span class="kt">weak_array_t</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">slot</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span>
<span class="p">}</span> <span class="n">weak_array_s</span><span class="p">,</span> <span class="o">*</span><span class="n">weak_array_t</span><span class="p">;</span>
<span class="k">typedef</span> <span class="n">weak_table_s</span> <span class="p">{</span>
<span class="n">type_s</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_WEAK_TABLE */</span>
<span class="kt">weak_array_t</span> <span class="n">keys</span><span class="p">,</span> <span class="n">values</span><span class="p">;</span>
<span class="p">}</span> <span class="n">weak_table_s</span><span class="p">,</span> <span class="o">*</span><span class="kt">weak_table_t</span><span class="p">;</span>
<span class="n">weak_array_t</span> <span class="n">keys</span><span class="p">,</span> <span class="n">values</span><span class="p">;</span>
<span class="p">}</span> <span class="n">weak_table_s</span><span class="p">,</span> <span class="o">*</span><span class="n">weak_table_t</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="nf">weak_array_find_dependent</span><span class="p">(</span><span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">)</span>
<span class="n">mps_addr_t</span> <span class="nf">weak_array_find_dependent</span><span class="p">(</span><span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">weak_array_t</span> <span class="n">a</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">weak_array_t</span> <span class="n">a</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="k">return</span> <span class="n">a</span><span class="o">-&gt;</span><span class="n">dependent</span><span class="p">;</span>
<span class="p">}</span>
<span class="kt">mps_res_t</span> <span class="nf">weak_array_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="n">mps_res_t</span> <span class="nf">weak_array_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">while</span> <span class="p">(</span><span class="n">base</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="kt">weak_array_t</span> <span class="n">a</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="n">weak_array_t</span> <span class="n">a</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">i</span><span class="p">,</span> <span class="n">length</span> <span class="o">=</span> <span class="n">a</span><span class="o">-&gt;</span><span class="n">length</span> <span class="o">&gt;&gt;</span> <span class="mi">1</span><span class="p">;</span> <span class="cm">/* untag */</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">a</span><span class="o">-&gt;</span><span class="n">dependent</span><span class="p">;</span>
<span class="n">MPS_FIX12</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
@ -201,7 +201,7 @@ <h3>Navigation</h3>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">length</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">a</span><span class="o">-&gt;</span><span class="n">slot</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="k">if</span> <span class="p">(</span><span class="n">MPS_FIX1</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="n">p</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="k">return</span> <span class="n">res</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">p</span> <span class="o">==</span> <span class="nb">NULL</span> <span class="o">&amp;&amp;</span> <span class="n">a</span><span class="o">-&gt;</span><span class="n">dependent</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* key/value was splatted: splat value/key too */</span>
@ -311,32 +311,63 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_awl</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_awl" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an AWL (Automatic Weak Linked)
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an AWL pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_awl</span><span class="p">(),</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="kt">mps_awl_find_dependent_t</span> <span class="n">find_dependent</span><span class="p">)</span>
<p>When creating an AWL pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
two <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.format</span></tt>; type
<a class="reference internal" href="../topic/format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the
objects allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan
method</em></a> and a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_AWL_FIND_DEPENDENT</span></tt> (member
<tt class="docutils literal"><span class="pre">.val.addr_method</span></tt>; type <a class="reference internal" href="#mps_awl_find_dependent_t" title="mps_awl_find_dependent_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_awl_find_dependent_t</span></tt></a>)
is a function that specifies how to find the <a class="reference internal" href="../glossary/d.html#term-dependent-object"><em class="xref std std-term">dependent
object</em></a> for an object in the pool.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_awl</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_AWL_FIND_DEPENDENT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">addr_method</span> <span class="o">=</span> <span class="n">find_dependent</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan
method</em></a> and a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">find_dependent</span></tt> is a function of type
<a class="reference internal" href="#mps_awl_find_dependent_t" title="mps_awl_find_dependent_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_awl_find_dependent_t</span></tt></a> that specifies how to find the
<a class="reference internal" href="../glossary/d.html#term-dependent-object"><em class="xref std std-term">dependent object</em></a> for an object in the pool.</p>
<p>When creating an allocation point on an AWL pool,
<a class="reference internal" href="../topic/allocation.html#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a> takes one extra argument:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="kt">mps_ap_t</span> <span class="o">*</span><span class="n">ap_o</span><span class="p">,</span> <span class="kt">mps_pool_t</span> <span class="n">pool</span><span class="p">,</span>
<span class="kt">mps_rank_t</span> <span class="n">rank</span><span class="p">)</span>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format and
find-dependent function like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_awl</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="n">mps_awl_find_dependent_t</span> <span class="n">find_dependent</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">rank</span></tt> specifies the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in objects
allocated on this allocation point. It must be
</div>
<p>When creating an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a> on an AWL pool,
<a class="reference internal" href="../topic/allocation.html#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a> requires one keyword argument:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_RANK</span></tt> (member <tt class="docutils literal"><span class="pre">.val.rank</span></tt>; type
<a class="reference internal" href="../topic/root.html#mps_rank_t" title="mps_rank_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_rank_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references
in objects allocated on this allocation point. It must be
<a class="reference internal" href="../topic/root.html#mps_rank_exact" title="mps_rank_exact"><tt class="xref c c-func docutils literal"><span class="pre">mps_rank_exact()</span></tt></a> (if the objects allocated on this
allocation point will contain <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact references</em></a>), or
<a class="reference internal" href="../topic/root.html#mps_rank_weak" title="mps_rank_weak"><tt class="xref c c-func docutils literal"><span class="pre">mps_rank_weak()</span></tt></a> (if the objects will contain <a class="reference internal" href="../glossary/w.html#term-weak-reference-1"><em class="xref std std-term">weak
references<sup>(1)</sup></em></a>).</p>
references<sup>(1)</sup></em></a>).</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ap</span><span class="p">,</span> <span class="n">awl_pool</span><span class="p">,</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_RANK</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">rank</span> <span class="o">=</span> <span class="n">mps_rank_weak</span><span class="p">()},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/allocation.html#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a>, pass the rank like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="n">mps_ap_t</span> <span class="o">*</span><span class="n">ap_o</span><span class="p">,</span> <span class="n">mps_pool_t</span> <span class="n">pool</span><span class="p">,</span>
<span class="n">mps_rank_t</span> <span class="n">rank</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="type">

8
mps/manual/html/pool/index.html
View file

@ -28,7 +28,7 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="next" title="1. Choosing a pool class" href="intro.html" />
<link rel="prev" title="19. Weak references" href="../topic/weak.html" />
<link rel="prev" title="20. Weak references" href="../topic/weak.html" />
</head>
<body>
<div class="related">
@ -41,7 +41,7 @@ <h3>Navigation</h3>
<a href="intro.html" title="1. Choosing a pool class"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../topic/weak.html" title="19. Weak references"
<a href="../topic/weak.html" title="20. Weak references"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
</ul>
@ -132,7 +132,7 @@ <h3>Navigation</h3>
</a></p>
<h4>Previous topic</h4>
<p class="topless"><a href="../topic/weak.html"
title="previous chapter">19. Weak references</a></p>
title="previous chapter">20. Weak references</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="intro.html"
title="next chapter">1. Choosing a pool class</a></p><h4>Downloads</h4>
@ -164,7 +164,7 @@ <h3>Navigation</h3>
<a href="intro.html" title="1. Choosing a pool class"
>next</a> |</li>
<li class="right" >
<a href="../topic/weak.html" title="19. Weak references"
<a href="../topic/weak.html" title="20. Weak references"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
</ul>

31
mps/manual/html/pool/lo.html
View file

@ -119,16 +119,31 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_lo</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_lo" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an LO (Leaf Object)
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an LO pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes one
extra argument:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_lo</span><span class="p">(),</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">)</span>
<p>When creating an LO pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> require one
<a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.format</span></tt>; type
<a class="reference internal" href="../topic/format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the
objects allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip
method</em></a>.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_lo</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip
method</em></a>.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format like
this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_lo</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>

45
mps/manual/html/pool/mfs.html
View file

@ -100,21 +100,40 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_mfs</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_mfs" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an MFS (Manual Fixed Small)
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an MFS pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_mfs</span><span class="p">(),</span>
<span class="kt">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">unit_size</span><span class="p">)</span>
<p>When creating an MFS pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
two <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MFS_UNIT_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of blocks that will be
allocated from this pool, in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>. It must be at
least one <a class="reference internal" href="../glossary/w.html#term-word"><em class="xref std std-term">word</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_EXTEND_BY</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of segment that the pool
will request from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>. It must be at least as big
as the unit size specified by the
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MFS_UNIT_SIZE</span></tt> keyword argument. If this is
not a multiple of the unit size, there will be wasted space in
each segment.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_mfs</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_MFS_UNIT_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">1024</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_EXTEND_BY</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">extend_size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of segment that the pool will
request from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>. It must be at least as big as
<tt class="docutils literal"><span class="pre">unit_size</span></tt>. If this is not a multiple of <tt class="docutils literal"><span class="pre">unit_size</span></tt>, there
will be wasted space in each segment.</p>
<p><tt class="docutils literal"><span class="pre">unit_size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of blocks that will be allocated
from this pool, in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>. It must be at least one
<a class="reference internal" href="../glossary/w.html#term-word"><em class="xref std std-term">word</em></a>.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the segment size and
unit size like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_mfs</span><span class="p">(),</span>
<span class="n">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">unit_size</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>

74
mps/manual/html/pool/mv.html
View file

@ -97,21 +97,42 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_mv</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_mv" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an MV (Manual Variable)
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an MV pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes three
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_mv</span><span class="p">(),</span>
<span class="kt">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">maximum_size</span><span class="p">)</span>
<p>When creating an MV pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
three <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_EXTEND_BY</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of segment that the pool
will request from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MEAN_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the predicted mean size of blocks that
will be allocated from the pool.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MAX_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the predicted maximum size of blocks that
will be allocated from the pool.</li>
</ul>
<p>The mean and maximum sizes are <em>hints</em> to the MPS: the pool will be
less efficient if these are wrong, but nothing will break.</p>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_mfs</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_MEAN_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">32</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MAX_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">1024</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_EXTEND_BY</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">extend_size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of segment that the pool will
request from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">average_size</span></tt> and <tt class="docutils literal"><span class="pre">maximum</span> <span class="pre">size</span></tt> are the predicted average
and maximum size of blocks that will be allocated from the pool.
These are hints to the MPS: the pool will be less efficient if
these are wrong.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the segment size,
mean size, and maximum size like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_mv</span><span class="p">(),</span>
<span class="n">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">maximum_size</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="function">
@ -119,20 +140,25 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_mv_debug</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_mv_debug" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../topic/debugging.html#topic-debugging"><em>debugging</em></a> version of the MV pool
class.</p>
<p>When creating a debugging MV pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>
takes four extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_mv_debug</span><span class="p">(),</span>
<p>When creating a debugging MV pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt>
requires four keyword arguments: <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_EXTEND_SIZE</span></tt>,
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MEAN_SIZE</span></tt>, <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MAX_SIZE</span></tt> are as
described above, and <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_POOL_DEBUG_OPTIONS</span></tt>
specifies the debugging options. See <tt class="xref c c-type docutils literal"><span class="pre">mps_debug_option_s</span></tt>.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the debugging
options, segment size, mean size, and maximum size like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_mv_debug</span><span class="p">(),</span>
<span class="n">mps_debug_option_s</span> <span class="n">debug_option</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">maximum_size</span><span class="p">)</span>
<span class="n">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">maximum_size</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">debug_option</span></tt> specifies the debugging options. See
<tt class="xref c c-type docutils literal"><span class="pre">mps_debug_option_s</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">extend_size</span></tt>, <tt class="docutils literal"><span class="pre">average_size</span></tt> and <tt class="docutils literal"><span class="pre">maximum_size</span></tt> are as
documented in <a class="reference internal" href="#mps_class_mv" title="mps_class_mv"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mv()</span></tt></a>.</p>
</div>
</dd></dl>
</div>

113
mps/manual/html/pool/mvff.html
View file

@ -126,32 +126,60 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_mvff</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_mvff" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an MVFF (Manual Variable First
Fit) <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an MVFF pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes six
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_mvff</span><span class="p">(),</span>
<span class="kt">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="kt">mps_align_t</span> <span class="n">alignment</span><span class="p">,</span>
<span class="kt">mps_bool_t</span> <span class="n">slot_high</span><span class="p">,</span>
<span class="kt">mps_bool_t</span> <span class="n">arena_high</span><span class="p">,</span>
<span class="kt">mps_bool_t</span> <span class="n">first_fit</span><span class="p">)</span>
<p>When creating an MVFF pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
six <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_EXTEND_BY</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of segment that the pool
will request from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MEAN_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the predicted mean size of blocks that will
be allocated from the pool. This is a <em>hint</em> to the MPS: the
pool will be less efficient if this is wrong, but nothing will
break.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ALIGN</span></tt> (member <tt class="docutils literal"><span class="pre">.val.align</span></tt>; type
<a class="reference internal" href="../topic/interface.html#mps_align_t" title="mps_align_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_align_t</span></tt></a>) is the <a class="reference internal" href="../glossary/a.html#term-alignment"><em class="xref std std-term">alignment</em></a> of addresses for
allocation (and freeing) in the pool. If an unaligned size is
passed to <a class="reference internal" href="../topic/allocation.html#mps_alloc" title="mps_alloc"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc()</span></tt></a> or <a class="reference internal" href="../topic/allocation.html#mps_free" title="mps_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_free()</span></tt></a>, it will be
rounded up to the pool&#8217;s alignment. The minimum alignment
supported by pools of this class is <tt class="docutils literal"><span class="pre">sizeof(void</span> <span class="pre">*)</span></tt>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_ARENA_HIGH</span></tt> (member <tt class="docutils literal"><span class="pre">.val.b</span></tt>; type
<a class="reference internal" href="../topic/interface.html#mps_bool_t" title="mps_bool_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_bool_t</span></tt></a>) indicates whether new segments for
buffered allocation are acquired at high addresses (if true), or
at low addresses (if false).</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_SLOT_HIGH</span></tt> (member <tt class="docutils literal"><span class="pre">.val.b</span></tt>; type
<a class="reference internal" href="../topic/interface.html#mps_bool_t" title="mps_bool_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_bool_t</span></tt></a>) is undocumented. It must have the same
value as <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_ARENA_HIGH</span></tt>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_FIRST_FIT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.b</span></tt>; type
<a class="reference internal" href="../topic/interface.html#mps_bool_t" title="mps_bool_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_bool_t</span></tt></a>) is undocumented and must be set to true.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_mvff</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_EXTEND_BY</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MEAN_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ALIGN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">align</span> <span class="o">=</span> <span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MVFF_ARENA_HIGH</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MVFF_SLOT_HIGH</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MVFF_FIRST_FIT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">b</span> <span class="o">=</span> <span class="mi">1</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">extend_size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of segment that the pool will
request from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">average_size</span></tt> is the predicted average size of blocks that will
be allocated from the pool.</p>
<p><tt class="docutils literal"><span class="pre">alignment</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-alignment"><em class="xref std std-term">alignment</em></a> of addresses for allocation
(and freeing) in the pool. If an unaligned size is passed to
<a class="reference internal" href="../topic/allocation.html#mps_alloc" title="mps_alloc"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc()</span></tt></a> or <a class="reference internal" href="../topic/allocation.html#mps_free" title="mps_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_free()</span></tt></a>, it will be rounded up
to the pool&#8217;s alignment. The minimum alignment supported by pools
of this class is <tt class="docutils literal"><span class="pre">sizeof(void</span> <span class="pre">*)</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">slot_high</span></tt> is undocumented. It must have the same value as
<tt class="docutils literal"><span class="pre">arena_high</span></tt>.</p>
<p>If <tt class="docutils literal"><span class="pre">arena_high</span></tt> is true, new segments for buffered allocation
are acquired at high addresses; if false, at low addresses.</p>
<p><tt class="docutils literal"><span class="pre">first_fit</span></tt> is undocumented and must be set to true.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the arguments like
this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_mvff</span><span class="p">(),</span>
<span class="n">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="n">mps_align_t</span> <span class="n">alignment</span><span class="p">,</span>
<span class="n">mps_bool_t</span> <span class="n">slot_high</span><span class="p">,</span>
<span class="n">mps_bool_t</span> <span class="n">arena_high</span><span class="p">,</span>
<span class="n">mps_bool_t</span> <span class="n">first_fit</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="function">
@ -159,22 +187,33 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_mvff_debug</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_mvff_debug" title="Permalink to this definition"></a></dt>
<dd><p>A <a class="reference internal" href="../topic/debugging.html#topic-debugging"><em>debugging</em></a> version of the MVFF pool
class.</p>
<p>When creating a debugging MVFF pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>
takes seven extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_mvff_debug</span><span class="p">(),</span>
<p>When creating a debugging MVFF pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt>
requires seven <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>.</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_EXTEND_BY</span></tt>, <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MEAN_SIZE</span></tt>,
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ALIGN</span></tt>, <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_ARENA_HIGH</span></tt>,
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_SLOT_HIGH</span></tt>, and
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_FIRST_FIT</span></tt> are as described above, and
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_POOL_DEBUG_OPTIONS</span></tt> specifies the debugging
:c:options. See <tt class="xref c c-type docutils literal"><span class="pre">mps_debug_option_s</span></tt>.</li>
</ul>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the debugging
options, and other arguments like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_mvff_debug</span><span class="p">(),</span>
<span class="n">mps_debug_option_s</span> <span class="n">debug_option</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="kt">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="kt">mps_align_t</span> <span class="n">alignment</span><span class="p">,</span>
<span class="kt">mps_bool_t</span> <span class="n">slot_high</span><span class="p">,</span>
<span class="kt">mps_bool_t</span> <span class="n">arena_high</span><span class="p">,</span>
<span class="kt">mps_bool_t</span> <span class="n">first_fit</span><span class="p">)</span>
<span class="n">mps_size_t</span> <span class="n">extend_size</span><span class="p">,</span>
<span class="n">mps_size_t</span> <span class="n">average_size</span><span class="p">,</span>
<span class="n">mps_align_t</span> <span class="n">alignment</span><span class="p">,</span>
<span class="n">mps_bool_t</span> <span class="n">slot_high</span><span class="p">,</span>
<span class="n">mps_bool_t</span> <span class="n">arena_high</span><span class="p">,</span>
<span class="n">mps_bool_t</span> <span class="n">first_fit</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">debug_option</span></tt> specifies the debugging options. See
<tt class="xref c c-type docutils literal"><span class="pre">mps_debug_option_s</span></tt>.</p>
<p>The other arguments are the same as for <a class="reference internal" href="#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a>.</p>
</div>
</dd></dl>
</div>

119
mps/manual/html/pool/mvt.html
View file

@ -122,64 +122,93 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_mvt</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_mvt" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an MVT (Manual Variable
Temporal) <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an MVT pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes five
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_mvt</span><span class="p">(),</span>
<span class="kt">size_t</span> <span class="n">minimum_size</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">mean_size</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">maximum_size</span><span class="p">,</span>
<span class="kt">mps_count_t</span> <span class="n">reserve_depth</span><span class="p">,</span>
<span class="kt">mps_count_t</span> <span class="n">fragmentation_limit</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">minimum_size</span></tt>, <tt class="docutils literal"><span class="pre">mean_size</span></tt>, and <tt class="docutils literal"><span class="pre">maximum_size</span></tt> are the
predicted minimum, mean, and maximum <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of
<a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">blocks</em></a> expected to be allocated in the pool. Blocks
smaller than <tt class="docutils literal"><span class="pre">minimum_size</span></tt> and larger than <tt class="docutils literal"><span class="pre">maximum_size</span></tt> may
be allocated, but the pool is not guaranteed to manage them
space-efficiently. Furthermore, partial freeing is not supported
for blocks larger than <tt class="docutils literal"><span class="pre">maximum_size</span></tt>; doing so will result in
the storage of the block never being reused. <tt class="docutils literal"><span class="pre">mean_size</span></tt> need
not be an accurate mean, although the pool will manage
<tt class="docutils literal"><span class="pre">mean_size</span></tt> blocks more efficiently if it is.</p>
<p><tt class="docutils literal"><span class="pre">reserve_depth</span></tt> is the expected hysteresis of the population of
the pool. When blocks are freed, the pool will retain sufficient
storage to allocate <tt class="docutils literal"><span class="pre">reserve_depth</span></tt> blocks of <tt class="docutils literal"><span class="pre">mean_size</span></tt> for
near term allocations (rather than immediately making that storage
available to other pools).</p>
<p>When creating an MVT pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires
five <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MIN_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the predicted minimum size of blocks that
will be allocated from the pool.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MEAN_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the predicted mean size of blocks that will
be allocated from the pool.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MAX_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is the predicted maximum size of blocks that
will be allocated from the pool. Partial freeing is not
supported for blocks larger than this; doing so will
result in the storage of the block never being reused.</li>
</ul>
<p>These three arguments are <em>hints</em> to the MPS: the pool will be
less efficient if they are wrong, but the only thing that will
break is the partial freeing of large blocks.</p>
<ul>
<li><p class="first"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVT_RESERVE_DEPTH</span></tt> (member <tt class="docutils literal"><span class="pre">.val.count</span></tt>;
type <tt class="xref c c-type docutils literal"><span class="pre">mps_count_t</span></tt>) is the expected hysteresis of the
population of the pool. When blocks are freed, the pool will
retain sufficient storage to allocate this many blocks of the mean
size for near term allocations (rather than immediately making
that storage available to other pools).</p>
<p>If a pool has a stable population, or one which only grows over
the lifetime of the pool, or one which grows steadily and then
shrinks steadily, use a reserve depth of 0.</p>
<p>It is always safe to use a reserve depth of 0, but if the
population typically fluctuates in a range (for example, the
client program repeatedly creates and destroys a subset of blocks
in a loop), it is more efficient for the pool to retain enough
storage to satisfy that fluctuation. For example, if a pool has an
object population that typically fluctuates between 8,000 and
10,000, use a reserve depth of 2,000.</p>
client program repeatedly creates and destroys a subset of
blocks in a loop), it is more efficient for the pool to retain
enough storage to satisfy that fluctuation. For example, if a
pool has an object population that typically fluctuates between
8,000 and 10,000, use a reserve depth of 2,000.</p>
<p>The reserve will not normally be available to other pools for
allocation, even when it is not used by the pool. If this is
undesirable, a reserve depth of 0 may be used for a pool whose
object population does vary, at a slight cost in efficiency. The
reserve does not guarantee any particular amount of allocation.</p>
<p><tt class="docutils literal"><span class="pre">fragmentation_limit</span></tt> is a percentage from 1 to 100 (inclusive).
It sets an upper limit on the space overhead of MVT, in case block
death times and allocations do not correlate well. If the free
space managed by the pool as a ratio of all the space managed by
the pool exceeds <tt class="docutils literal"><span class="pre">fragmentation_limit</span></tt>, the pool falls back to a
first fit allocation policy, exploiting space more efficiently at
a cost in time efficiency. A fragmentation limit of 0 would cause
the pool to operate as a first-fit pool, at a significant cost in
time efficiency: therefore this is not permitted.</p>
</li>
<li><p class="first"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVT_FRAG_LIMIT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.count</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">mps_count_t</span></tt>) is a percentage from 1 to 100
(inclusive). It sets an upper limit on the space overhead of an
MVT pool, in case block death times and allocations do not
correlate well. If the free space managed by the pool as a ratio
of all the space managed by the pool exceeds the fragmentation
limit, the pool falls back to a first fit allocation policy,
exploiting space more efficiently at a cost in time efficiency.
A fragmentation limit of 0 would cause the pool to operate as a
first-fit pool, at a significant cost in time efficiency:
therefore this is not permitted.</p>
<p>A fragmentation limit of 100 causes the pool to always use
temporal fit (unless resources are exhausted). If the objects
allocated in the pool have similar lifetime expectancies, this
mode will have the best time- and space-efficiency. If the objects
have widely varying lifetime expectancies, this mode will be
time-efficient, but may be space-inefficient. An intermediate
setting can be used to limit the space-inefficiency of temporal
fit due to varying object life expectancies.</p>
mode will have the best time- and space-efficiency. If the
objects have widely varying lifetime expectancies, this mode
will be time-efficient, but may be space-inefficient. An
intermediate setting can be used to limit the space-inefficiency
of temporal fit due to varying object life expectancies.</p>
</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_mvt</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_MIN_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">4</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MEAN_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">32</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MAX_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">1024</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MVT_RESERVE_DEPTH</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="mi">256</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_MVT_FRAG_LIMIT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="mi">50</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the arguments like
this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_mvt</span><span class="p">(),</span>
<span class="kt">size_t</span> <span class="n">minimum_size</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">mean_size</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">maximum_size</span><span class="p">,</span>
<span class="n">mps_count_t</span> <span class="n">reserve_depth</span><span class="p">,</span>
<span class="n">mps_count_t</span> <span class="n">fragmentation_limit</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>

60
mps/manual/html/pool/snc.html
View file

@ -112,25 +112,55 @@ <h3>Navigation</h3>
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_snc</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_snc" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an SNC (Stack No Check)
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an SNC pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes one
extra argument:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="kt">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="kt">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="kt">mps_class_t</span> <span class="n">mps_class_snc</span><span class="p">(),</span>
<span class="kt">mps_fmt_t</span> <span class="n">fmt</span><span class="p">)</span>
<p>When creating an SNC pool, <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> requires one
<a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt> (member <tt class="docutils literal"><span class="pre">.val.format</span></tt>; type
<a class="reference internal" href="../topic/format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the
objects allocated in the pool. The format must provide a
<a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a>, a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding
method</em></a>.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_snc</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan
method</em></a>, a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a>.</p>
<p>When creating an allocation point on an SNC pool,
<a class="reference internal" href="../topic/allocation.html#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a> takes one extra argument:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="kt">mps_ap_t</span> <span class="o">*</span><span class="n">ap_o</span><span class="p">,</span> <span class="kt">mps_pool_t</span> <span class="n">pool</span><span class="p">,</span>
<span class="kt">mps_rank_t</span> <span class="n">rank</span><span class="p">)</span>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>, pass the format like
this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_snc</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">rank</span></tt> specifies the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in objects
allocated on this allocation point. It must be
<a class="reference internal" href="../topic/root.html#mps_rank_exact" title="mps_rank_exact"><tt class="xref c c-func docutils literal"><span class="pre">mps_rank_exact()</span></tt></a>.</p>
</div>
<p>When creating an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a> on an SNC pool,
<a class="reference internal" href="../topic/allocation.html#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a> requires one keyword argument:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_RANK</span></tt> (member <tt class="docutils literal"><span class="pre">.val.rank</span></tt>; type
<a class="reference internal" href="../topic/root.html#mps_rank_t" title="mps_rank_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_rank_t</span></tt></a>) specifies the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references
in objects allocated on this allocation point. It must be
<a class="reference internal" href="../topic/root.html#mps_rank_exact" title="mps_rank_exact"><tt class="xref c c-func docutils literal"><span class="pre">mps_rank_exact()</span></tt></a>.</li>
</ul>
<p>For example, in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_ap_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">ap</span><span class="p">,</span> <span class="n">awl_pool</span><span class="p">,</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_RANK</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">rank</span> <span class="o">=</span> <span class="n">mps_rank_exact</span><span class="p">()},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="../topic/allocation.html#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a>, pass the rank like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_ap_create</span><span class="p">(</span><span class="n">mps_ap_t</span> <span class="o">*</span><span class="n">ap_o</span><span class="p">,</span> <span class="n">mps_pool_t</span> <span class="n">pool</span><span class="p">,</span>
<span class="n">mps_rank_t</span> <span class="n">rank</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>

2
mps/manual/html/searchindex.js
View file

File diff suppressed because one or more lines are too long

132
mps/manual/html/topic/allocation.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>5. Allocation &mdash; Memory Pool System 1.111.0 documentation</title>
<title>6. Allocation &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="6. Object formats" href="format.html" />
<link rel="prev" title="4. Pools" href="pool.html" />
<link rel="next" title="7. Object formats" href="format.html" />
<link rel="prev" title="5. Pools" href="pool.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="format.html" title="6. Object formats"
<a href="format.html" title="7. Object formats"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pool.html" title="4. Pools"
<a href="pool.html" title="5. Pools"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,9 +55,9 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="allocation">
<span id="topic-allocation"></span><span id="index-0"></span><h1>5. Allocation<a class="headerlink" href="#allocation" title="Permalink to this headline"></a></h1>
<span id="topic-allocation"></span><span id="index-0"></span><h1>6. Allocation<a class="headerlink" href="#allocation" title="Permalink to this headline"></a></h1>
<div class="section" id="manual-allocation">
<span id="index-1"></span><h2>5.1. Manual allocation<a class="headerlink" href="#manual-allocation" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>6.1. Manual allocation<a class="headerlink" href="#manual-allocation" title="Permalink to this headline"></a></h2>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">Not all <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> support this interface:
@ -108,7 +108,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="allocation-points">
<span id="index-2"></span><h2>5.2. Allocation points<a class="headerlink" href="#allocation-points" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>6.2. Allocation points<a class="headerlink" href="#allocation-points" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">Allocation points</em></a> provide fast, <a class="reference internal" href="../glossary/i.html#term-inline-allocation-1"><em class="xref std std-term">inline</em></a>, nearly <a class="reference internal" href="../glossary/l.html#term-lock-free"><em class="xref std std-term">lock-free</em></a> allocation.
They allow code to allocate without calling an allocation function:
this is vital for performance in languages or programs that allocate
@ -123,16 +123,18 @@ <h3>Navigation</h3>
</dd></dl>
<dl class="function">
<dt id="mps_ap_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_create</tt><big>(</big><a class="reference internal" href="#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;*ap_o</em>, <a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em>, ...<big>)</big><a class="headerlink" href="#mps_ap_create" title="Permalink to this definition"></a></dt>
<dt id="mps_ap_create_k">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_create_k</tt><big>(</big><a class="reference internal" href="#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;*ap_o</em>, <a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em>, <a class="reference internal" href="keyword.html#mps_arg_s" title="mps_arg_s">mps_arg_s</a><em>&nbsp;args[]</em><big>)</big><a class="headerlink" href="#mps_ap_create_k" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a> in a <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ap_o</span></tt> points to a location that will hold the address of the
allocation point, if successful.</p>
<p><tt class="docutils literal"><span class="pre">pool</span></tt> is the pool.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> are <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a> specific to the pool class
to which <tt class="docutils literal"><span class="pre">pool</span></tt> belong. See the documentation for that pool
class. (Most pool classes don&#8217;t take any keyword arguments; in
those cases you can pass <a class="reference internal" href="keyword.html#mps_args_none" title="mps_args_none"><tt class="xref c c-macro docutils literal"><span class="pre">mps_args_none</span></tt></a>.)</p>
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if successful, or another
<a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> if not.</p>
<p>Some pool classes require additional arguments to be passed to
<a class="reference internal" href="#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a>. See the documentation for the pool class.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">An allocation point must not be used by more than one
@ -147,10 +149,32 @@ <h3>Navigation</h3>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_ap_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_create</tt><big>(</big><a class="reference internal" href="#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;*ap_o</em>, <a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em>, ...<big>)</big><a class="headerlink" href="#mps_ap_create" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <a class="reference internal" href="#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <a class="reference internal" href="#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a> that takes its extra
arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> variable argument list
mechanism.</p>
</dd></dl>
<dl class="function">
<dt id="mps_ap_create_v">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_create_v</tt><big>(</big><a class="reference internal" href="#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;*ap_o</em>, <a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em>, va_list<em>&nbsp;args</em><big>)</big><a class="headerlink" href="#mps_ap_create_v" title="Permalink to this definition"></a></dt>
<dd><p>An alternative to <a class="reference internal" href="#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a> that takes its extra
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <a class="reference internal" href="#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <a class="reference internal" href="#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a> that takes its extra
arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> <tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
</dd></dl>
@ -166,7 +190,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="allocation-point-protocol">
<span id="topic-allocation-point-protocol"></span><span id="index-3"></span><h2>5.3. Allocation point protocol<a class="headerlink" href="#allocation-point-protocol" title="Permalink to this headline"></a></h2>
<span id="topic-allocation-point-protocol"></span><span id="index-3"></span><h2>6.3. Allocation point protocol<a class="headerlink" href="#allocation-point-protocol" title="Permalink to this headline"></a></h2>
<p>This protocol is designed to work with <a class="reference internal" href="../glossary/i.html#term-incremental-garbage-collection"><em class="xref std std-term">incremental garbage
collection</em></a> and multiple <a class="reference internal" href="../glossary/t.html#term-thread"><em class="xref std std-term">threads</em></a>, where between any
two instructions in the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>, the MPS may run part
@ -231,10 +255,10 @@ <h3>Navigation</h3>
</ol>
<p>The usual implementation of the allocation point protocol in <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
is thus:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="cm">/* handle the error */</span><span class="p">;</span>
<span class="cm">/* p is now an ambiguous reference to the reserved block */</span>
<span class="n">obj</span> <span class="o">=</span> <span class="n">p</span><span class="p">;</span>
@ -336,20 +360,20 @@ <h3>Navigation</h3>
</div>
<div class="section" id="example-allocating-a-symbol">
<span id="index-4"></span><h2>5.4. Example: allocating a symbol<a class="headerlink" href="#example-allocating-a-symbol" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>6.4. Example: allocating a symbol<a class="headerlink" href="#example-allocating-a-symbol" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">symbol_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_SYMBOL */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_SYMBOL */</span>
<span class="kt">size_t</span> <span class="n">length</span><span class="p">;</span> <span class="cm">/* length of symbol string (excl. NUL) */</span>
<span class="kt">char</span> <span class="n">string</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> <span class="cm">/* symbol string, NUL terminated */</span>
<span class="p">}</span> <span class="n">symbol_s</span><span class="p">,</span> <span class="o">*</span><span class="kt">symbol_t</span><span class="p">;</span>
<span class="p">}</span> <span class="n">symbol_s</span><span class="p">,</span> <span class="o">*</span><span class="n">symbol_t</span><span class="p">;</span>
<span class="kt">symbol_t</span> <span class="nf">make_symbol</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">length</span><span class="p">,</span> <span class="kt">char</span> <span class="n">string</span><span class="p">[])</span>
<span class="n">symbol_t</span> <span class="nf">make_symbol</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">length</span><span class="p">,</span> <span class="kt">char</span> <span class="n">string</span><span class="p">[])</span>
<span class="p">{</span>
<span class="kt">symbol_t</span> <span class="n">symbol</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">symbol_t</span> <span class="n">symbol</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="n">offsetof</span><span class="p">(</span><span class="n">symbol_s</span><span class="p">,</span> <span class="n">string</span><span class="p">)</span> <span class="o">+</span> <span class="n">length</span><span class="o">+</span><span class="mi">1</span><span class="p">);</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">addr</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory in make_symbol&quot;</span><span class="p">);</span>
<span class="n">symbol</span> <span class="o">=</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">symbol</span><span class="o">-&gt;</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_SYMBOL</span><span class="p">;</span>
@ -362,7 +386,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="cautions">
<span id="topic-allocation-cautions"></span><span id="index-5"></span><h2>5.5. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<span id="topic-allocation-cautions"></span><span id="index-5"></span><h2>6.5. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<p>While a block is reserved but not yet committed:</p>
<ol class="arabic simple">
<li>The client program must not create an <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact reference</em></a> to
@ -411,24 +435,24 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="example-inserting-into-a-doubly-linked-list">
<span id="index-6"></span><h2>5.6. Example: inserting into a doubly linked list<a class="headerlink" href="#example-inserting-into-a-doubly-linked-list" title="Permalink to this headline"></a></h2>
<span id="index-6"></span><h2>6.6. Example: inserting into a doubly linked list<a class="headerlink" href="#example-inserting-into-a-doubly-linked-list" title="Permalink to this headline"></a></h2>
<p>This example contains several mistakes. See the highlighted lines:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">link_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_LINK */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_LINK */</span>
<span class="cm">/* all three of these pointers are fixed: */</span>
<span class="k">struct</span> <span class="n">link_s</span> <span class="o">*</span><span class="n">prev</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">link_s</span> <span class="o">*</span><span class="n">next</span><span class="p">;</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="p">}</span> <span class="n">link_s</span><span class="p">,</span> <span class="o">*</span><span class="kt">link_t</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="p">}</span> <span class="n">link_s</span><span class="p">,</span> <span class="o">*</span><span class="n">link_t</span><span class="p">;</span>
<span class="cm">/* insert &#39;obj&#39; into the doubly-linked list after &#39;head&#39; */</span>
<span class="kt">link_t</span> <span class="nf">insert_link</span><span class="p">(</span><span class="kt">link_t</span> <span class="n">head</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">obj</span><span class="p">)</span>
<span class="n">link_t</span> <span class="nf">insert_link</span><span class="p">(</span><span class="n">link_t</span> <span class="n">head</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">obj</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="kt">link_t</span> <span class="n">link</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="n">link_t</span> <span class="n">link</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">link_s</span><span class="p">));</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory&quot;</span><span class="p">);</span>
<span class="n">link</span> <span class="o">=</span> <span class="n">p</span><span class="p">;</span>
<span class="n">link</span><span class="o">-&gt;</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_LINK</span><span class="p">;</span>
@ -454,13 +478,13 @@ <h3>Navigation</h3>
scan method, so it must be initialized before the call to commit.</li>
</ol>
<p>A correct version of <tt class="docutils literal"><span class="pre">insert_link</span></tt> looks like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">link_t</span> <span class="nf">insert_link</span><span class="p">(</span><span class="kt">link_t</span> <span class="n">head</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">obj</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">link_t</span> <span class="nf">insert_link</span><span class="p">(</span><span class="n">link_t</span> <span class="n">head</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">obj</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="kt">link_t</span> <span class="n">link</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="n">link_t</span> <span class="n">link</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="n">ALIGN</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">link_s</span><span class="p">));</span>
<span class="k">do</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">mps_reserve</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">ap</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;out of memory&quot;</span><span class="p">);</span>
<span class="n">link</span> <span class="o">=</span> <span class="n">p</span><span class="p">;</span>
<span class="n">link</span><span class="o">-&gt;</span><span class="n">type</span> <span class="o">=</span> <span class="n">TYPE_LINK</span><span class="p">;</span>
@ -476,7 +500,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="allocation-point-implementation">
<span id="topic-allocation-point-implementation"></span><span id="index-7"></span><h2>5.7. Allocation point implementation<a class="headerlink" href="#allocation-point-implementation" title="Permalink to this headline"></a></h2>
<span id="topic-allocation-point-implementation"></span><span id="index-7"></span><h2>6.7. Allocation point implementation<a class="headerlink" href="#allocation-point-implementation" title="Permalink to this headline"></a></h2>
<p>An allocation point consists of a structure of type <a class="reference internal" href="#mps_ap_s" title="mps_ap_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_ap_s</span></tt></a>
and an associated <a class="reference internal" href="../glossary/b.html#term-buffer"><em class="xref std std-term">buffer</em></a>.</p>
<div class="figure align-center">
@ -574,9 +598,9 @@ <h3>Navigation</h3>
<dd><p>The type of the structure used to represent <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation
points</em></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_ap_s</span> <span class="p">{</span>
<span class="kt">mps_addr_t</span> <span class="n">init</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">alloc</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">init</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">alloc</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">;</span>
<span class="cm">/* ... private fields ... */</span>
<span class="p">}</span> <span class="n">mps_ap_s</span><span class="p">;</span>
</pre></div>
@ -588,7 +612,7 @@ <h3>Navigation</h3>
provides very fast allocation, and defers the need for
synchronization in a multi-threaded environment.</p>
<p>Create an allocation point for a pool by calling
<a class="reference internal" href="#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a>, and allocate memory via one by calling
<a class="reference internal" href="#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create_k()</span></tt></a>, and allocate memory via one by calling
<a class="reference internal" href="#mps_reserve" title="mps_reserve"><tt class="xref c c-func docutils literal"><span class="pre">mps_reserve()</span></tt></a> and <a class="reference internal" href="#mps_commit" title="mps_commit"><tt class="xref c c-func docutils literal"><span class="pre">mps_commit()</span></tt></a>.</p>
</dd></dl>
@ -631,24 +655,24 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5. Allocation</a><ul>
<li><a class="reference internal" href="#manual-allocation">5.1. Manual allocation</a></li>
<li><a class="reference internal" href="#allocation-points">5.2. Allocation points</a></li>
<li><a class="reference internal" href="#allocation-point-protocol">5.3. Allocation point protocol</a></li>
<li><a class="reference internal" href="#example-allocating-a-symbol">5.4. Example: allocating a symbol</a></li>
<li><a class="reference internal" href="#cautions">5.5. Cautions</a></li>
<li><a class="reference internal" href="#example-inserting-into-a-doubly-linked-list">5.6. Example: inserting into a doubly linked list</a></li>
<li><a class="reference internal" href="#allocation-point-implementation">5.7. Allocation point implementation</a></li>
<li><a class="reference internal" href="#">6. Allocation</a><ul>
<li><a class="reference internal" href="#manual-allocation">6.1. Manual allocation</a></li>
<li><a class="reference internal" href="#allocation-points">6.2. Allocation points</a></li>
<li><a class="reference internal" href="#allocation-point-protocol">6.3. Allocation point protocol</a></li>
<li><a class="reference internal" href="#example-allocating-a-symbol">6.4. Example: allocating a symbol</a></li>
<li><a class="reference internal" href="#cautions">6.5. Cautions</a></li>
<li><a class="reference internal" href="#example-inserting-into-a-doubly-linked-list">6.6. Example: inserting into a doubly linked list</a></li>
<li><a class="reference internal" href="#allocation-point-implementation">6.7. Allocation point implementation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="pool.html"
title="previous chapter">4. Pools</a></p>
title="previous chapter">5. Pools</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="format.html"
title="next chapter">6. Object formats</a></p><h4>Downloads</h4>
title="next chapter">7. Object formats</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -674,10 +698,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="format.html" title="6. Object formats"
<a href="format.html" title="7. Object formats"
>next</a> |</li>
<li class="right" >
<a href="pool.html" title="4. Pools"
<a href="pool.html" title="5. Pools"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

185
mps/manual/html/topic/arena.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>3. Arenas &mdash; Memory Pool System 1.111.0 documentation</title>
<title>4. Arenas &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="4. Pools" href="pool.html" />
<link rel="prev" title="2. Error handing" href="error.html" />
<link rel="next" title="5. Pools" href="pool.html" />
<link rel="prev" title="3. Error handing" href="error.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="pool.html" title="4. Pools"
<a href="pool.html" title="5. Pools"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="error.html" title="2. Error handing"
<a href="error.html" title="3. Error handing"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,11 +55,11 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="arenas">
<span id="topic-arena"></span><span id="index-0"></span><h1>3. Arenas<a class="headerlink" href="#arenas" title="Permalink to this headline"></a></h1>
<span id="topic-arena"></span><span id="index-0"></span><h1>4. Arenas<a class="headerlink" href="#arenas" title="Permalink to this headline"></a></h1>
<p>An arena is an object that encapsulates the state of the Memory Pool
System, and tells it where to get the memory it manages. You typically
start a session with the MPS by creating an arena with
<a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> and end the session by destroying it with
<a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> and end the session by destroying it with
<a class="reference internal" href="#mps_arena_destroy" title="mps_arena_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_destroy()</span></tt></a>. The only function you might need to call
before making an arena is <a class="reference internal" href="telemetry.html#mps_telemetry_control" title="mps_telemetry_control"><tt class="xref c c-func docutils literal"><span class="pre">mps_telemetry_control()</span></tt></a>.</p>
<p>Before destroying an arena, you must first destroy all objects and
@ -110,32 +110,48 @@ <h3>Navigation</h3>
</dd></dl>
<dl class="function">
<dt id="mps_arena_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_class</em>, ...<big>)</big><a class="headerlink" href="#mps_arena_create" title="Permalink to this definition"></a></dt>
<dt id="mps_arena_create_k">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create_k</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_class</em>, <a class="reference internal" href="keyword.html#mps_arg_s" title="mps_arg_s">mps_arg_s</a><em>&nbsp;args[]</em><big>)</big><a class="headerlink" href="#mps_arena_create_k" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena_o</span></tt> points to a location that will hold a pointer to the new
arena.</p>
<p><tt class="docutils literal"><span class="pre">arena_class</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-arena-class"><em class="xref std std-term">arena class</em></a>.</p>
<p>Some arena classes require additional arguments to be passed to
<a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>. See the documentation for the arena
class.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> are <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a> specific to the arena
class. See the documentation for the arena class.</p>
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the arena is created
successfully, or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> otherwise.</p>
<p>The arena persists until it is destroyed by calling
<a class="reference internal" href="#mps_arena_destroy" title="mps_arena_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_destroy()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">There&#8217;s an alternative function <a class="reference internal" href="#mps_arena_create_v" title="mps_arena_create_v"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_v()</span></tt></a>
that takes its extra arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
<tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_class</em>, ...<big>)</big><a class="headerlink" href="#mps_arena_create" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> that takes its
extra arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> variable argument
list mechanism.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_create_v">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create_v</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_class</em>, va_list<em>&nbsp;args</em><big>)</big><a class="headerlink" href="#mps_arena_create_v" title="Permalink to this definition"></a></dt>
<dd><p>An alternative to <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> that takes its extra
arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> <tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> that takes its
extra arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> <tt class="docutils literal"><span class="pre">va_list</span></tt>
mechanism.</p>
</dd></dl>
<dl class="function">
@ -154,7 +170,7 @@ <h3>Navigation</h3>
</dd></dl>
<div class="section" id="client-arenas">
<span id="topic-arena-client"></span><span id="index-2"></span><h2>3.1. Client arenas<a class="headerlink" href="#client-arenas" title="Permalink to this headline"></a></h2>
<span id="topic-arena-client"></span><span id="index-2"></span><h2>4.1. Client arenas<a class="headerlink" href="#client-arenas" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpsacl.h&quot;</span>
</pre></div>
</div>
@ -164,18 +180,24 @@ <h3>Navigation</h3>
<dd><p>Return the <a class="reference internal" href="../glossary/a.html#term-arena-class"><em class="xref std std-term">arena class</em></a> for a <a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client arena</em></a>.</p>
<p>A client arena gets its managed memory from the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a>. This memory chunk is passed when the arena is created.</p>
<p>When creating a client arena, <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="kt">mps_arena_t</span> <span class="o">*</span><span class="n">arena_o</span><span class="p">,</span>
<span class="kt">mps_arena_class_t</span> <span class="n">mps_arena_class_cl</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
<p>When creating a client arena, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> requires two
<a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_CL_ADDR</span></tt> (member <tt class="docutils literal"><span class="pre">.val.addr</span></tt>; type
<a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_addr_t</span></tt></a>) is the <a class="reference internal" href="../glossary/a.html#term-address"><em class="xref std std-term">address</em></a> of the chunk of memory
that will be managed by the arena.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is its size.</li>
</ul>
<p>For example (in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>):</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_ARENA_CL_ADDR</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">addr</span> <span class="o">=</span> <span class="n">base</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="n">size</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">base</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-address"><em class="xref std std-term">address</em></a> of the chunk of memory that will
be managed by the arena.</p>
<p><tt class="docutils literal"><span class="pre">size</span></tt> is its <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a>.</p>
<p>If the chunk is too small to hold the internal arena structures,
<a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> returns <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a>. In
<a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> returns <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a>. In
this case, you need to use a (much) larger chunk.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
@ -183,6 +205,17 @@ <h3>Navigation</h3>
call <a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a> later on.</p>
<p class="last">Client arenas have no mechanism for returning unused memory.</p>
</div>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>, pass the size and base
address like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="n">mps_arena_t</span> <span class="o">*</span><span class="n">arena_o</span><span class="p">,</span>
<span class="n">mps_arena_class_t</span> <span class="n">mps_arena_class_cl</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="function">
@ -198,7 +231,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="virtual-memory-arenas">
<span id="topic-arena-vm"></span><span id="index-3"></span><h2>3.2. Virtual memory arenas<a class="headerlink" href="#virtual-memory-arenas" title="Permalink to this headline"></a></h2>
<span id="topic-arena-vm"></span><span id="index-3"></span><h2>4.2. Virtual memory arenas<a class="headerlink" href="#virtual-memory-arenas" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpsavm.h&quot;</span>
</pre></div>
</div>
@ -213,11 +246,16 @@ <h3>Navigation</h3>
where to place <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">blocks</em></a>, which reduces
<a class="reference internal" href="../glossary/f.html#term-fragmentation"><em class="xref std std-term">fragmentation</em></a> and helps make <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a>
more efficient.</p>
<p>When creating a virtual memory arena, <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>
takes one extra argument:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="kt">mps_arena_t</span> <span class="o">*</span><span class="n">arena_o</span><span class="p">,</span>
<span class="kt">mps_arena_class_t</span> <span class="n">arena_class_vm</span><span class="p">(),</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
<p>When creating a virtual memory arena, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a>
requires one <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt> (member <tt class="docutils literal"><span class="pre">.val.size</span></tt>; type
<tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>).</li>
</ul>
<p>For example (in <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>):</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="n">size</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">size</span></tt> is the initial amount of virtual address space, in
@ -235,19 +273,43 @@ <h3>Navigation</h3>
more times it has to extend its address space, the less
efficient garbage collection will become.</p>
</div>
<p>An optional <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a> may be passed, but is
only used on the Windows operating system:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_VMW3_TOP_DOWN</span></tt> (member <tt class="docutils literal"><span class="pre">.val.b</span></tt>; type
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_bool_t</span></tt></a>).</li>
</ul>
<p>If true, the arena will allocate address space starting at the
highest possible address and working downwards through memory.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This causes the arena to pass the <tt class="docutils literal"><span class="pre">MEM_TOP_DOWN</span></tt> flag to
<a class="reference external" href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa366887%28v=vs.85%29.aspx">VirtualAlloc</a>.</p>
</div>
<p>If the MPS fails to reserve adequate address space to place the
arena in, <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> returns
arena in, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> returns
<a class="reference internal" href="error.html#MPS_RES_RESOURCE" title="MPS_RES_RESOURCE"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_RESOURCE</span></tt></a>. Possibly this means that other parts
of the program are reserving too much virtual memory.</p>
<p>If the MPS fails to allocate memory for the internal arena
structures, <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> returns
structures, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> returns
<a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a>. Either <tt class="docutils literal"><span class="pre">size</span></tt> was far too small or
the operating system refused to provide enough memory.</p>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>, pass the size like
this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="n">mps_arena_t</span> <span class="o">*</span><span class="n">arena_o</span><span class="p">,</span>
<span class="n">mps_arena_class_t</span> <span class="n">arena_class_vm</span><span class="p">(),</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>
<div class="section" id="arena-properties">
<span id="index-4"></span><h2>3.3. Arena properties<a class="headerlink" href="#arena-properties" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>4.3. Arena properties<a class="headerlink" href="#arena-properties" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_collections">
<a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a> <tt class="descname">mps_collections</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_collections" title="Permalink to this definition"></a></dt>
@ -349,15 +411,16 @@ <h3>Navigation</h3>
reserved via the operating system&#8217;s virtual memory interface.</p>
<p>For a <a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client arena</em></a>, this is the sum of the usable portions
of the chunks of memory passed to the arena by the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> via <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> and
program</em></a> via <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> and
<a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">For a client arena, the reserved address may be lower than the
sum of the <tt class="docutils literal"><span class="pre">size</span></tt> arguments passed to
<a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a> and <a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a>,
because the arena may be unable to use the whole of each chunk
for reasons of alignment.</p>
sum of the <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt> keyword argument
passed to <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> and the <tt class="docutils literal"><span class="pre">size</span></tt>
arguments passed to <a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a>, because the
arena may be unable to use the whole of each chunk for reasons
of alignment.</p>
</div>
</dd></dl>
@ -418,7 +481,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="arena-states">
<span id="index-5"></span><h2>3.4. Arena states<a class="headerlink" href="#arena-states" title="Permalink to this headline"></a></h2>
<span id="index-5"></span><h2>4.4. Arena states<a class="headerlink" href="#arena-states" title="Permalink to this headline"></a></h2>
<p>An arena is always in one of three states.</p>
<ol class="arabic">
<li><p id="index-6">In the <em>unclamped state</em>, garbage collection may take place,
@ -496,7 +559,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="running-garbage-collections">
<span id="index-9"></span><h2>3.5. Running garbage collections<a class="headerlink" href="#running-garbage-collections" title="Permalink to this headline"></a></h2>
<span id="index-9"></span><h2>4.5. Running garbage collections<a class="headerlink" href="#running-garbage-collections" title="Permalink to this headline"></a></h2>
<p>The Memory Pool System&#8217;s garbage collector runs <a class="reference internal" href="../glossary/a.html#term-asynchronous-garbage-collector"><em class="xref std std-term">asynchronously</em></a> and <a class="reference internal" href="../glossary/i.html#term-incremental-garbage-collection"><em class="xref std std-term">incrementally</em></a>. This means that it is not normally
necessary to tell it when to start garbage collections, or to wait
until it has finished collecting. (But if your program has idle time
@ -550,7 +613,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="using-idle-time-for-collection">
<span id="topic-arena-idle"></span><span id="index-10"></span><h2>3.6. Using idle time for collection<a class="headerlink" href="#using-idle-time-for-collection" title="Permalink to this headline"></a></h2>
<span id="topic-arena-idle"></span><span id="index-10"></span><h2>4.6. Using idle time for collection<a class="headerlink" href="#using-idle-time-for-collection" title="Permalink to this headline"></a></h2>
<p>Some types of program have &#8220;idle time&#8221; in which they are waiting for
an external event such as user input or network activity. The MPS
provides a function, <a class="reference internal" href="#mps_arena_step" title="mps_arena_step"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_step()</span></tt></a>, for making use of idle
@ -620,7 +683,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="arena-introspection">
<span id="index-11"></span><h2>3.7. Arena introspection<a class="headerlink" href="#arena-introspection" title="Permalink to this headline"></a></h2>
<span id="index-11"></span><h2>4.7. Arena introspection<a class="headerlink" href="#arena-introspection" title="Permalink to this headline"></a></h2>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>Introspection functions covered in other chapters are:</p>
@ -664,7 +727,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="protection-interface">
<span id="index-12"></span><h2>3.8. Protection interface<a class="headerlink" href="#protection-interface" title="Permalink to this headline"></a></h2>
<span id="index-12"></span><h2>4.8. Protection interface<a class="headerlink" href="#protection-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_arena_expose">
void <tt class="descname">mps_arena_expose</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_expose" title="Permalink to this definition"></a></dt>
@ -776,25 +839,25 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">3. Arenas</a><ul>
<li><a class="reference internal" href="#client-arenas">3.1. Client arenas</a></li>
<li><a class="reference internal" href="#virtual-memory-arenas">3.2. Virtual memory arenas</a></li>
<li><a class="reference internal" href="#arena-properties">3.3. Arena properties</a></li>
<li><a class="reference internal" href="#arena-states">3.4. Arena states</a></li>
<li><a class="reference internal" href="#running-garbage-collections">3.5. Running garbage collections</a></li>
<li><a class="reference internal" href="#using-idle-time-for-collection">3.6. Using idle time for collection</a></li>
<li><a class="reference internal" href="#arena-introspection">3.7. Arena introspection</a></li>
<li><a class="reference internal" href="#protection-interface">3.8. Protection interface</a></li>
<li><a class="reference internal" href="#">4. Arenas</a><ul>
<li><a class="reference internal" href="#client-arenas">4.1. Client arenas</a></li>
<li><a class="reference internal" href="#virtual-memory-arenas">4.2. Virtual memory arenas</a></li>
<li><a class="reference internal" href="#arena-properties">4.3. Arena properties</a></li>
<li><a class="reference internal" href="#arena-states">4.4. Arena states</a></li>
<li><a class="reference internal" href="#running-garbage-collections">4.5. Running garbage collections</a></li>
<li><a class="reference internal" href="#using-idle-time-for-collection">4.6. Using idle time for collection</a></li>
<li><a class="reference internal" href="#arena-introspection">4.7. Arena introspection</a></li>
<li><a class="reference internal" href="#protection-interface">4.8. Protection interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="error.html"
title="previous chapter">2. Error handing</a></p>
title="previous chapter">3. Error handing</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pool.html"
title="next chapter">4. Pools</a></p><h4>Downloads</h4>
title="next chapter">5. Pools</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -820,10 +883,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="pool.html" title="4. Pools"
<a href="pool.html" title="5. Pools"
>next</a> |</li>
<li class="right" >
<a href="error.html" title="2. Error handing"
<a href="error.html" title="3. Error handing"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

36
mps/manual/html/topic/cache.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>14. Segregated allocation caches &mdash; Memory Pool System 1.111.0 documentation</title>
<title>15. Segregated allocation caches &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="15. Allocation patterns" href="pattern.html" />
<link rel="prev" title="13. Location dependency" href="location.html" />
<link rel="next" title="16. Allocation patterns" href="pattern.html" />
<link rel="prev" title="14. Location dependency" href="location.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="pattern.html" title="15. Allocation patterns"
<a href="pattern.html" title="16. Allocation patterns"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="location.html" title="13. Location dependency"
<a href="location.html" title="14. Location dependency"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="segregated-allocation-caches">
<span id="topic-cache"></span><span id="index-0"></span><h1>14. Segregated allocation caches<a class="headerlink" href="#segregated-allocation-caches" title="Permalink to this headline"></a></h1>
<span id="topic-cache"></span><span id="index-0"></span><h1>15. Segregated allocation caches<a class="headerlink" href="#segregated-allocation-caches" title="Permalink to this headline"></a></h1>
<p>A <em class="dfn">segregated allocation cache</em> is a data structure that can be
attached to any <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually managed</em></a>
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>, that maintains a <a class="reference internal" href="../glossary/s.html#term-segregated-free-list"><em class="xref std std-term">segregated free list</em></a>, that is,
@ -70,7 +70,7 @@ <h3>Navigation</h3>
number of relatively short-lived 8-byte objects, we might create a
cache as follows:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_sac_class_s</span> <span class="n">classes</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="p">{{</span><span class="mi">8</span><span class="p">,</span> <span class="mi">100</span><span class="p">,</span> <span class="mi">10</span><span class="p">},</span> <span class="p">{</span><span class="mi">128</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">1</span><span class="p">}};</span>
<span class="kt">mps_sac_t</span> <span class="n">sac</span><span class="p">;</span>
<span class="n">mps_sac_t</span> <span class="n">sac</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_sac_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">sac</span><span class="p">,</span> <span class="n">pool</span><span class="p">,</span> <span class="k">sizeof</span> <span class="n">classes</span> <span class="o">/</span> <span class="k">sizeof</span> <span class="n">classes</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">classes</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span>
@ -83,8 +83,8 @@ <h3>Navigation</h3>
(using <a class="reference internal" href="#mps_sac_free" title="mps_sac_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_sac_free()</span></tt></a> or <a class="reference internal" href="#MPS_SAC_FREE_FAST" title="MPS_SAC_FREE_FAST"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SAC_FREE_FAST()</span></tt></a>) return
the block to the appopriate free list for its size. For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">Foo</span> <span class="o">*</span><span class="n">foo</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_sac_alloc</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">sac</span><span class="p">,</span> <span class="k">sizeof</span> <span class="o">*</span><span class="n">foo</span><span class="p">,</span> <span class="nb">false</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span>
@ -121,7 +121,7 @@ <h3>Navigation</h3>
between the cache and the pool.</p>
</div>
<div class="section" id="cache-interface">
<span id="index-1"></span><h2>14.1. Cache interface<a class="headerlink" href="#cache-interface" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>15.1. Cache interface<a class="headerlink" href="#cache-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_sac_t">
<tt class="descname">mps_sac_t</tt><a class="headerlink" href="#mps_sac_t" title="Permalink to this definition"></a></dt>
@ -271,7 +271,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="allocation-interface">
<span id="index-2"></span><h2>14.2. Allocation interface<a class="headerlink" href="#allocation-interface" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>15.2. Allocation interface<a class="headerlink" href="#allocation-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_sac_alloc">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_sac_alloc</tt><big>(</big><a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;*p_o</em>, <a class="reference internal" href="#mps_sac_t" title="mps_sac_t">mps_sac_t</a><em>&nbsp;sac</em>, size_t<em>&nbsp;size</em>, <a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a><em>&nbsp;has_reservoir_permit</em><big>)</big><a class="headerlink" href="#mps_sac_alloc" title="Permalink to this definition"></a></dt>
@ -400,19 +400,19 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">14. Segregated allocation caches</a><ul>
<li><a class="reference internal" href="#cache-interface">14.1. Cache interface</a></li>
<li><a class="reference internal" href="#allocation-interface">14.2. Allocation interface</a></li>
<li><a class="reference internal" href="#">15. Segregated allocation caches</a><ul>
<li><a class="reference internal" href="#cache-interface">15.1. Cache interface</a></li>
<li><a class="reference internal" href="#allocation-interface">15.2. Allocation interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="location.html"
title="previous chapter">13. Location dependency</a></p>
title="previous chapter">14. Location dependency</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pattern.html"
title="next chapter">15. Allocation patterns</a></p><h4>Downloads</h4>
title="next chapter">16. Allocation patterns</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -438,10 +438,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="pattern.html" title="15. Allocation patterns"
<a href="pattern.html" title="16. Allocation patterns"
>next</a> |</li>
<li class="right" >
<a href="location.html" title="13. Location dependency"
<a href="location.html" title="14. Location dependency"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

42
mps/manual/html/topic/collection.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>10. Garbage collection &mdash; Memory Pool System 1.111.0 documentation</title>
<title>11. Garbage collection &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="11. Messages" href="message.html" />
<link rel="prev" title="9. Roots" href="root.html" />
<link rel="next" title="12. Messages" href="message.html" />
<link rel="prev" title="10. Roots" href="root.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="message.html" title="11. Messages"
<a href="message.html" title="12. Messages"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="root.html" title="9. Roots"
<a href="root.html" title="10. Roots"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,9 +55,9 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="garbage-collection">
<span id="topic-collection"></span><span id="index-0"></span><h1>10. Garbage collection<a class="headerlink" href="#garbage-collection" title="Permalink to this headline"></a></h1>
<span id="topic-collection"></span><span id="index-0"></span><h1>11. Garbage collection<a class="headerlink" href="#garbage-collection" title="Permalink to this headline"></a></h1>
<div class="section" id="generation-chains">
<span id="index-1"></span><h2>10.1. Generation chains<a class="headerlink" href="#generation-chains" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>11.1. Generation chains<a class="headerlink" href="#generation-chains" title="Permalink to this headline"></a></h2>
<p>A <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a> describes the structure of the
<a class="reference internal" href="../glossary/g.html#term-generation"><em class="xref std std-term">generations</em></a> in a set of <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically managed</em></a> <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pools</em></a>. The same generation
chain should be used for all pools whose blocks live and die together.</p>
@ -74,8 +74,8 @@ <h3>Navigation</h3>
<span class="p">{</span> <span class="mi">2048</span><span class="p">,</span> <span class="mf">0.4</span> <span class="p">},</span>
<span class="p">};</span>
<span class="kt">mps_chain_t</span> <span class="n">chain</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_chain_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">chain</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span>
<span class="k">sizeof</span><span class="p">(</span><span class="n">gen_params</span><span class="p">)</span> <span class="o">/</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">gen_params</span><span class="p">[</span><span class="mi">0</span><span class="p">]),</span>
<span class="n">gen_params</span><span class="p">);</span>
@ -139,7 +139,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="scheduling-of-collections">
<span id="topic-collection-schedule"></span><span id="index-2"></span><h2>10.2. Scheduling of collections<a class="headerlink" href="#scheduling-of-collections" title="Permalink to this headline"></a></h2>
<span id="topic-collection-schedule"></span><span id="index-2"></span><h2>11.2. Scheduling of collections<a class="headerlink" href="#scheduling-of-collections" title="Permalink to this headline"></a></h2>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">It&#8217;s likely that the algorithm the MPS uses to schedule its
@ -193,7 +193,7 @@ <h3>Navigation</h3>
slices up front and then find that it is idle later on.</p>
</div>
<div class="section" id="garbage-collection-start-messages">
<span id="index-3"></span><h2>10.3. Garbage collection start messages<a class="headerlink" href="#garbage-collection-start-messages" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>11.3. Garbage collection start messages<a class="headerlink" href="#garbage-collection-start-messages" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_message_type_gc_start">
<a class="reference internal" href="message.html#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a> <tt class="descname">mps_message_type_gc_start</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_message_type_gc_start" title="Permalink to this definition"></a></dt>
@ -234,7 +234,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="garbage-collection-messages">
<span id="index-4"></span><h2>10.4. Garbage collection messages<a class="headerlink" href="#garbage-collection-messages" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>11.4. Garbage collection messages<a class="headerlink" href="#garbage-collection-messages" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_message_type_gc">
<a class="reference internal" href="message.html#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a> <tt class="descname">mps_message_type_gc</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_message_type_gc" title="Permalink to this definition"></a></dt>
@ -329,21 +329,21 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">10. Garbage collection</a><ul>
<li><a class="reference internal" href="#generation-chains">10.1. Generation chains</a></li>
<li><a class="reference internal" href="#scheduling-of-collections">10.2. Scheduling of collections</a></li>
<li><a class="reference internal" href="#garbage-collection-start-messages">10.3. Garbage collection start messages</a></li>
<li><a class="reference internal" href="#garbage-collection-messages">10.4. Garbage collection messages</a></li>
<li><a class="reference internal" href="#">11. Garbage collection</a><ul>
<li><a class="reference internal" href="#generation-chains">11.1. Generation chains</a></li>
<li><a class="reference internal" href="#scheduling-of-collections">11.2. Scheduling of collections</a></li>
<li><a class="reference internal" href="#garbage-collection-start-messages">11.3. Garbage collection start messages</a></li>
<li><a class="reference internal" href="#garbage-collection-messages">11.4. Garbage collection messages</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="root.html"
title="previous chapter">9. Roots</a></p>
title="previous chapter">10. Roots</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="message.html"
title="next chapter">11. Messages</a></p><h4>Downloads</h4>
title="next chapter">12. Messages</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -369,10 +369,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="message.html" title="11. Messages"
<a href="message.html" title="12. Messages"
>next</a> |</li>
<li class="right" >
<a href="root.html" title="9. Roots"
<a href="root.html" title="10. Roots"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

12
mps/manual/html/topic/critical.html
View file

@ -164,18 +164,18 @@ <h2>3.4. The format scanner<a class="headerlink" href="#the-format-scanner" titl
of the format creation functions. (See <a class="reference internal" href="format.html#topic-format"><em>Object formats</em></a>.)</p>
<p>Here is an example of part of a format scanner for scanning contiguous
runs of pointers, from <tt class="docutils literal"><span class="pre">fmtdy.c</span></tt>, the scanner for the <a class="reference external" href="http://opendylan.org/">Open Dylan</a> runtime:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">dylan_scan_contig</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">mps_ss</span><span class="p">,</span>
<span class="kt">mps_addr_t</span> <span class="o">*</span><span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="o">*</span><span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">dylan_scan_contig</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">mps_ss</span><span class="p">,</span>
<span class="n">mps_addr_t</span> <span class="o">*</span><span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="o">*</span><span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span> <span class="cm">/* reference cursor */</span>
<span class="kt">mps_addr_t</span> <span class="n">r</span><span class="p">;</span> <span class="cm">/* reference to be fixed */</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span> <span class="cm">/* reference cursor */</span>
<span class="n">mps_addr_t</span> <span class="n">r</span><span class="p">;</span> <span class="cm">/* reference to be fixed */</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">mps_ss</span><span class="p">)</span> <span class="p">{</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="nl">loop:</span> <span class="k">if</span><span class="p">(</span><span class="n">p</span> <span class="o">&gt;=</span> <span class="n">limit</span><span class="p">)</span> <span class="k">goto</span> <span class="n">out</span><span class="p">;</span>
<span class="n">r</span> <span class="o">=</span> <span class="o">*</span><span class="n">p</span><span class="o">++</span><span class="p">;</span>
<span class="k">if</span><span class="p">(((</span><span class="kt">mps_word_t</span><span class="p">)</span><span class="n">r</span><span class="o">&amp;</span><span class="mi">3</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="cm">/* pointers tagged with 0 */</span>
<span class="k">if</span><span class="p">(((</span><span class="n">mps_word_t</span><span class="p">)</span><span class="n">r</span><span class="o">&amp;</span><span class="mi">3</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="cm">/* pointers tagged with 0 */</span>
<span class="k">goto</span> <span class="n">loop</span><span class="p">;</span> <span class="cm">/* not a pointer */</span>
<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">MPS_FIX1</span><span class="p">(</span><span class="n">mps_ss</span><span class="p">,</span> <span class="n">r</span><span class="p">))</span> <span class="k">goto</span> <span class="n">loop</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">mps_ss</span><span class="p">,</span> <span class="n">p</span><span class="o">-</span><span class="mi">1</span><span class="p">);</span>

37
mps/manual/html/topic/debugging.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>17. Debugging pools &mdash; Memory Pool System 1.111.0 documentation</title>
<title>18. Debugging pools &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="18. Telemetry" href="telemetry.html" />
<link rel="prev" title="16. Allocation frames" href="frame.html" />
<link rel="next" title="19. Telemetry" href="telemetry.html" />
<link rel="prev" title="17. Allocation frames" href="frame.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="telemetry.html" title="18. Telemetry"
<a href="telemetry.html" title="19. Telemetry"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="frame.html" title="16. Allocation frames"
<a href="frame.html" title="17. Allocation frames"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="debugging-pools">
<span id="topic-debugging"></span><span id="index-0"></span><h1>17. Debugging pools<a class="headerlink" href="#debugging-pools" title="Permalink to this headline"></a></h1>
<span id="topic-debugging"></span><span id="index-0"></span><h1>18. Debugging pools<a class="headerlink" href="#debugging-pools" title="Permalink to this headline"></a></h1>
<p>Several <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> have debugging counterparts:</p>
<table border="1" class="docutils">
<colgroup>
@ -115,18 +115,23 @@ <h3>Navigation</h3>
<span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">)</span><span class="s">&quot;postpost&quot;</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span>
<span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">)</span><span class="s">&quot;freefree&quot;</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span>
<span class="p">};</span>
<span class="kt">mps_pool_t</span> <span class="n">pool</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_ams_debug</span><span class="p">(),</span>
<span class="o">&amp;</span><span class="n">debug_options</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">fmt</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">chain</span><span class="p">)</span>
<span class="n">mps_pool_t</span> <span class="n">pool</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_ams_debug</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_POOL_DEBUG_OPTIONS</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">pool_debug_options</span> <span class="o">=</span> <span class="o">&amp;</span><span class="n">debug_options</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="o">&amp;</span><span class="n">fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">chain</span> <span class="o">=</span> <span class="o">&amp;</span><span class="n">chain</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;can&#39;t create debug pool&quot;</span><span class="p">);</span>
</pre></div>
</div>
<dl class="type">
<dt id="mps_pool_debug_option_s">
<tt class="descname">mps_pool_debug_option_s</tt><a class="headerlink" href="#mps_pool_debug_option_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to pass options to
<a class="reference internal" href="pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> for debugging <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a>.</p>
<dd><p>The type of the structure passed as the
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_POOL_DEBUG_OPTIONS</span></tt> keyword argument to
<tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> when creating a debugging <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool
class</em></a>.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_pool_debug_option_s</span> <span class="p">{</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">fence_template</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">fence_size</span><span class="p">;</span>
@ -189,10 +194,10 @@ <h3>Navigation</h3>
</a></p>
<h4>Previous topic</h4>
<p class="topless"><a href="frame.html"
title="previous chapter">16. Allocation frames</a></p>
title="previous chapter">17. Allocation frames</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="telemetry.html"
title="next chapter">18. Telemetry</a></p><h4>Downloads</h4>
title="next chapter">19. Telemetry</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -218,10 +223,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="telemetry.html" title="18. Telemetry"
<a href="telemetry.html" title="19. Telemetry"
>next</a> |</li>
<li class="right" >
<a href="frame.html" title="16. Allocation frames"
<a href="frame.html" title="17. Allocation frames"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

42
mps/manual/html/topic/error.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>2. Error handing &mdash; Memory Pool System 1.111.0 documentation</title>
<title>3. Error handing &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="3. Arenas" href="arena.html" />
<link rel="prev" title="1. Interface conventions" href="interface.html" />
<link rel="next" title="4. Arenas" href="arena.html" />
<link rel="prev" title="2. Keyword arguments" href="keyword.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="arena.html" title="3. Arenas"
<a href="arena.html" title="4. Arenas"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="interface.html" title="1. Interface conventions"
<a href="keyword.html" title="2. Keyword arguments"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="error-handing">
<span id="topic-error"></span><span id="index-0"></span><h1>2. Error handing<a class="headerlink" href="#error-handing" title="Permalink to this headline"></a></h1>
<span id="topic-error"></span><span id="index-0"></span><h1>3. Error handing<a class="headerlink" href="#error-handing" title="Permalink to this headline"></a></h1>
<p>Operations in the Memory Pool System that might fail return a
<a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> of type <a class="reference internal" href="#mps_res_t" title="mps_res_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_res_t</span></tt></a>, rather than a
&#8220;special value&#8221; of the return type.</p>
@ -99,7 +99,7 @@ <h3>Navigation</h3>
</dd></dl>
<div class="section" id="result-codes">
<h2>2.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink to this headline"></a></h2>
<h2>3.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink to this headline"></a></h2>
<dl class="macro">
<dt id="MPS_RES_COMMIT_LIMIT">
<tt class="descname">MPS_RES_COMMIT_LIMIT</tt><a class="headerlink" href="#MPS_RES_COMMIT_LIMIT" title="Permalink to this definition"></a></dt>
@ -204,7 +204,7 @@ <h2>2.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink
</div>
<div class="section" id="assertions">
<span id="topic-error-assertion"></span><span id="index-1"></span><h2>2.2. Assertions<a class="headerlink" href="#assertions" title="Permalink to this headline"></a></h2>
<span id="topic-error-assertion"></span><span id="index-1"></span><h2>3.2. Assertions<a class="headerlink" href="#assertions" title="Permalink to this headline"></a></h2>
<p>Bugs in the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> may violate the invariants that the
MPS relies on. Most functions in the MPS (in most <em>varieties</em>; see
below) assert the correctness of their data structures, so these bugs
@ -225,7 +225,7 @@ <h2>2.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink
</div>
</div>
<div class="section" id="common-assertions-and-their-causes">
<span id="topic-error-cause"></span><span id="index-2"></span><h2>2.3. Common assertions and their causes<a class="headerlink" href="#common-assertions-and-their-causes" title="Permalink to this headline"></a></h2>
<span id="topic-error-cause"></span><span id="index-2"></span><h2>3.3. Common assertions and their causes<a class="headerlink" href="#common-assertions-and-their-causes" title="Permalink to this headline"></a></h2>
<p>This section lists some commonly encountered assertions and suggests
likely causes. If you encounter an assertion not listed here (or an
assertion that is listed here but for which you discovered a different
@ -241,7 +241,7 @@ <h2>2.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink
<a class="reference internal" href="debugging.html#topic-debugging"><em>Debugging pools</em></a>.</div></blockquote>
<p><tt class="docutils literal"><span class="pre">format.c:</span> <span class="pre">SigCheck</span> <span class="pre">Format:</span> <span class="pre">format</span></tt></p>
<blockquote>
<div>The client program called <a class="reference internal" href="pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> for a
<div>The client program called <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> for a
<a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> like <a class="reference internal" href="../pool/amc.html#pool-amc"><em>AMC (Automatic Mostly-Copying)</em></a> that requires a
<a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>, but passed something other than a
<a class="reference internal" href="format.html#mps_fmt_t" title="mps_fmt_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_t</span></tt></a> for this argument.</div></blockquote>
@ -277,7 +277,7 @@ <h2>2.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink
condition?</div></blockquote>
</div>
<div class="section" id="varieties">
<span id="index-3"></span><h2>2.4. Varieties<a class="headerlink" href="#varieties" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>3.4. Varieties<a class="headerlink" href="#varieties" title="Permalink to this headline"></a></h2>
<p>The MPS has three behaviours with respect to internal checking and
<a class="reference internal" href="telemetry.html#topic-telemetry"><em>telemetry</em></a>, which need to be selected at
compile time, by defining one of the following preprocessor
@ -327,21 +327,21 @@ <h2>2.1. Result codes<a class="headerlink" href="#result-codes" title="Permalink
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">2. Error handing</a><ul>
<li><a class="reference internal" href="#result-codes">2.1. Result codes</a></li>
<li><a class="reference internal" href="#assertions">2.2. Assertions</a></li>
<li><a class="reference internal" href="#common-assertions-and-their-causes">2.3. Common assertions and their causes</a></li>
<li><a class="reference internal" href="#varieties">2.4. Varieties</a></li>
<li><a class="reference internal" href="#">3. Error handing</a><ul>
<li><a class="reference internal" href="#result-codes">3.1. Result codes</a></li>
<li><a class="reference internal" href="#assertions">3.2. Assertions</a></li>
<li><a class="reference internal" href="#common-assertions-and-their-causes">3.3. Common assertions and their causes</a></li>
<li><a class="reference internal" href="#varieties">3.4. Varieties</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="interface.html"
title="previous chapter">1. Interface conventions</a></p>
<p class="topless"><a href="keyword.html"
title="previous chapter">2. Keyword arguments</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="arena.html"
title="next chapter">3. Arenas</a></p><h4>Downloads</h4>
title="next chapter">4. Arenas</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -367,10 +367,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="arena.html" title="3. Arenas"
<a href="arena.html" title="4. Arenas"
>next</a> |</li>
<li class="right" >
<a href="interface.html" title="1. Interface conventions"
<a href="keyword.html" title="2. Keyword arguments"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

40
mps/manual/html/topic/finalization.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>12. Finalization &mdash; Memory Pool System 1.111.0 documentation</title>
<title>13. Finalization &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="13. Location dependency" href="location.html" />
<link rel="prev" title="11. Messages" href="message.html" />
<link rel="next" title="14. Location dependency" href="location.html" />
<link rel="prev" title="12. Messages" href="message.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="location.html" title="13. Location dependency"
<a href="location.html" title="14. Location dependency"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="message.html" title="11. Messages"
<a href="message.html" title="12. Messages"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,14 +55,14 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="finalization">
<span id="topic-finalization"></span><span id="index-0"></span><h1>12. Finalization<a class="headerlink" href="#finalization" title="Permalink to this headline"></a></h1>
<span id="topic-finalization"></span><span id="index-0"></span><h1>13. Finalization<a class="headerlink" href="#finalization" title="Permalink to this headline"></a></h1>
<p>It is sometimes necessary to perform actions when a block of memory
<a class="reference internal" href="../glossary/d.html#term-dead"><em class="xref std std-term">dies</em></a>. For example, a block may represent the
acquisition of an external resource such as a file handle or a network
connection. When the block dies, the corresponding resource must be
released. This procedure is known as <a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a>.</p>
<p>A block requiring finalization must be registered by calling <a class="reference internal" href="#mps_finalize" title="mps_finalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_finalize()</span></tt></a>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_addr_t</span> <span class="n">ref</span> <span class="o">=</span> <span class="n">block_requiring_finalization</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_addr_t</span> <span class="n">ref</span> <span class="o">=</span> <span class="n">block_requiring_finalization</span><span class="p">;</span>
<span class="n">mps_finalize</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">ref</span><span class="p">);</span>
</pre></div>
</div>
@ -126,7 +126,7 @@ <h3>Navigation</h3>
</div>
<p>See <a class="reference internal" href="message.html#topic-message"><em>Messages</em></a> for details of the message mechanism.</p>
<div class="section" id="multiple-finalizations">
<span id="index-1"></span><h2>12.1. Multiple finalizations<a class="headerlink" href="#multiple-finalizations" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>13.1. Multiple finalizations<a class="headerlink" href="#multiple-finalizations" title="Permalink to this headline"></a></h2>
<p>A block may be registered for finalization multiple times. A block
that has been registered for finalization <em>n</em> times will be finalized
at most <em>n</em> times.</p>
@ -139,7 +139,7 @@ <h3>Navigation</h3>
either behaviour.</p>
</div>
<div class="section" id="cautions">
<span id="topic-finalization-cautions"></span><span id="index-2"></span><h2>12.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<span id="topic-finalization-cautions"></span><span id="index-2"></span><h2>13.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<ol class="arabic">
<li><p class="first">Don&#8217;t rely on finalization for your program to work. Treat it as an
optimization that enables the freeing of resources that the
@ -208,7 +208,7 @@ <h3>Navigation</h3>
</ol>
</div>
<div class="section" id="finalization-interface">
<span id="index-3"></span><h2>12.3. Finalization interface<a class="headerlink" href="#finalization-interface" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>13.3. Finalization interface<a class="headerlink" href="#finalization-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_finalize">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_finalize</tt><big>(</big><a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;*ref_p</em><big>)</big><a class="headerlink" href="#mps_finalize" title="Permalink to this definition"></a></dt>
@ -251,7 +251,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="finalization-messages">
<span id="index-4"></span><h2>12.4. Finalization messages<a class="headerlink" href="#finalization-messages" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>13.4. Finalization messages<a class="headerlink" href="#finalization-messages" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_message_type_finalization">
<a class="reference internal" href="message.html#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a> <tt class="descname">mps_message_type_finalization</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_message_type_finalization" title="Permalink to this definition"></a></dt>
@ -320,21 +320,21 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">12. Finalization</a><ul>
<li><a class="reference internal" href="#multiple-finalizations">12.1. Multiple finalizations</a></li>
<li><a class="reference internal" href="#cautions">12.2. Cautions</a></li>
<li><a class="reference internal" href="#finalization-interface">12.3. Finalization interface</a></li>
<li><a class="reference internal" href="#finalization-messages">12.4. Finalization messages</a></li>
<li><a class="reference internal" href="#">13. Finalization</a><ul>
<li><a class="reference internal" href="#multiple-finalizations">13.1. Multiple finalizations</a></li>
<li><a class="reference internal" href="#cautions">13.2. Cautions</a></li>
<li><a class="reference internal" href="#finalization-interface">13.3. Finalization interface</a></li>
<li><a class="reference internal" href="#finalization-messages">13.4. Finalization messages</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="message.html"
title="previous chapter">11. Messages</a></p>
title="previous chapter">12. Messages</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="location.html"
title="next chapter">13. Location dependency</a></p><h4>Downloads</h4>
title="next chapter">14. Location dependency</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -360,10 +360,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="location.html" title="13. Location dependency"
<a href="location.html" title="14. Location dependency"
>next</a> |</li>
<li class="right" >
<a href="message.html" title="11. Messages"
<a href="message.html" title="12. Messages"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

90
mps/manual/html/topic/format.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>6. Object formats &mdash; Memory Pool System 1.111.0 documentation</title>
<title>7. Object formats &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="7. Scanning" href="scanning.html" />
<link rel="prev" title="5. Allocation" href="allocation.html" />
<link rel="next" title="8. Scanning" href="scanning.html" />
<link rel="prev" title="6. Allocation" href="allocation.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="scanning.html" title="7. Scanning"
<a href="scanning.html" title="8. Scanning"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="allocation.html" title="5. Allocation"
<a href="allocation.html" title="6. Allocation"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="object-formats">
<span id="topic-format"></span><span id="index-0"></span><h1>6. Object formats<a class="headerlink" href="#object-formats" title="Permalink to this headline"></a></h1>
<span id="topic-format"></span><span id="index-0"></span><h1>7. Object formats<a class="headerlink" href="#object-formats" title="Permalink to this headline"></a></h1>
<p>The need for some means of describing objects in the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> comes from <a class="reference internal" href="../glossary/t.html#term-trace"><em class="xref std std-term">tracing</em></a> and <a class="reference internal" href="../glossary/m.html#term-moving-memory-manager"><em class="xref std std-term">moving</em></a>. During tracing, when an object is <a class="reference internal" href="../glossary/s.html#term-scan"><em class="xref std std-term">scanned</em></a>, all the <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> in the object must be
identified so that the objects they point to can be scanned in their
@ -82,7 +82,7 @@ <h3>Navigation</h3>
</dd></dl>
<div class="section" id="creating-an-object-format">
<span id="index-1"></span><h2>6.1. Creating an object format<a class="headerlink" href="#creating-an-object-format" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>7.1. Creating an object format<a class="headerlink" href="#creating-an-object-format" title="Permalink to this headline"></a></h2>
<p>Different <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> use different sets of format methods
and values (for example, a non-moving pool does not need forwarding
objects, so its object formats do not need to contain a forward
@ -114,15 +114,17 @@ <h3>Navigation</h3>
<span class="n">obj_pad</span>
<span class="p">};</span>
<span class="kt">mps_pool_t</span> <span class="n">obj_pool</span><span class="p">;</span>
<span class="kt">mps_fmt_t</span> <span class="n">obj_fmt</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_pool_t</span> <span class="n">obj_pool</span><span class="p">;</span>
<span class="n">mps_fmt_t</span> <span class="n">obj_fmt</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_fmt_create_A</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_fmt</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">obj_fmt_s</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj format&quot;</span><span class="p">);</span>
<span class="cm">/* obj_fmt created successfully */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">pool_class</span><span class="p">,</span> <span class="n">obj_fmt</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">pool_class</span><span class="p">,</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">obj_fmt</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj pool&quot;</span><span class="p">);</span>
</pre></div>
</div>
@ -132,13 +134,13 @@ <h3>Navigation</h3>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant A.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_A_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="kt">mps_fmt_copy_t</span> <span class="n">copy</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="n">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="n">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="n">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="n">mps_fmt_copy_t</span> <span class="n">copy</span><span class="p">;</span>
<span class="n">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="n">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="n">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_A_s</span><span class="p">;</span>
</pre></div>
</div>
@ -189,14 +191,14 @@ <h3>Navigation</h3>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant B.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_B_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="kt">mps_fmt_copy_t</span> <span class="n">copy</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="kt">mps_fmt_class_t</span> <span class="n">mps_class</span><span class="p">;</span>
<span class="n">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="n">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="n">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="n">mps_fmt_copy_t</span> <span class="n">copy</span><span class="p">;</span>
<span class="n">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="n">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="n">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="n">mps_fmt_class_t</span> <span class="n">mps_class</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_B_s</span><span class="p">;</span>
</pre></div>
</div>
@ -223,12 +225,12 @@ <h3>Navigation</h3>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant auto-header.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_auto_header_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="n">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="n">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="n">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="n">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="n">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="n">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">mps_headerSize</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_auto_header_s</span><span class="p">;</span>
</pre></div>
@ -301,7 +303,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="cautions">
<span id="topic-format-cautions"></span><span id="index-2"></span><h2>6.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<span id="topic-format-cautions"></span><span id="index-2"></span><h2>7.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<ol class="arabic">
<li><p class="first">The MPS guarantees that format methods have exclusive access to the
object for the duration of the call. This guarantee may entail
@ -353,7 +355,7 @@ <h3>Navigation</h3>
</ol>
</div>
<div class="section" id="format-methods">
<span id="index-3"></span><h2>6.3. Format methods<a class="headerlink" href="#format-methods" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>7.3. Format methods<a class="headerlink" href="#format-methods" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_fmt_class_t">
<a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a> <tt class="descname">(*mps_fmt_class_t)</tt><big>(</big><a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#mps_fmt_class_t" title="Permalink to this definition"></a></dt>
@ -495,7 +497,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="object-format-introspection">
<span id="index-4"></span><h2>6.4. Object format introspection<a class="headerlink" href="#object-format-introspection" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>7.4. Object format introspection<a class="headerlink" href="#object-format-introspection" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_addr_fmt">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_addr_fmt</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*fmt_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#mps_addr_fmt" title="Permalink to this definition"></a></dt>
@ -598,21 +600,21 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">6. Object formats</a><ul>
<li><a class="reference internal" href="#creating-an-object-format">6.1. Creating an object format</a></li>
<li><a class="reference internal" href="#cautions">6.2. Cautions</a></li>
<li><a class="reference internal" href="#format-methods">6.3. Format methods</a></li>
<li><a class="reference internal" href="#object-format-introspection">6.4. Object format introspection</a></li>
<li><a class="reference internal" href="#">7. Object formats</a><ul>
<li><a class="reference internal" href="#creating-an-object-format">7.1. Creating an object format</a></li>
<li><a class="reference internal" href="#cautions">7.2. Cautions</a></li>
<li><a class="reference internal" href="#format-methods">7.3. Format methods</a></li>
<li><a class="reference internal" href="#object-format-introspection">7.4. Object format introspection</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="allocation.html"
title="previous chapter">5. Allocation</a></p>
title="previous chapter">6. Allocation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="scanning.html"
title="next chapter">7. Scanning</a></p><h4>Downloads</h4>
title="next chapter">8. Scanning</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -638,10 +640,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="scanning.html" title="7. Scanning"
<a href="scanning.html" title="8. Scanning"
>next</a> |</li>
<li class="right" >
<a href="allocation.html" title="5. Allocation"
<a href="allocation.html" title="6. Allocation"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

20
mps/manual/html/topic/frame.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>16. Allocation frames &mdash; Memory Pool System 1.111.0 documentation</title>
<title>17. Allocation frames &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="17. Debugging pools" href="debugging.html" />
<link rel="prev" title="15. Allocation patterns" href="pattern.html" />
<link rel="next" title="18. Debugging pools" href="debugging.html" />
<link rel="prev" title="16. Allocation patterns" href="pattern.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="debugging.html" title="17. Debugging pools"
<a href="debugging.html" title="18. Debugging pools"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pattern.html" title="15. Allocation patterns"
<a href="pattern.html" title="16. Allocation patterns"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="allocation-frames">
<span id="topic-frame"></span><span id="index-0"></span><h1>16. Allocation frames<a class="headerlink" href="#allocation-frames" title="Permalink to this headline"></a></h1>
<span id="topic-frame"></span><span id="index-0"></span><h1>17. Allocation frames<a class="headerlink" href="#allocation-frames" title="Permalink to this headline"></a></h1>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.111.</p>
@ -145,10 +145,10 @@ <h3>Navigation</h3>
</a></p>
<h4>Previous topic</h4>
<p class="topless"><a href="pattern.html"
title="previous chapter">15. Allocation patterns</a></p>
title="previous chapter">16. Allocation patterns</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="debugging.html"
title="next chapter">17. Debugging pools</a></p><h4>Downloads</h4>
title="next chapter">18. Debugging pools</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -174,10 +174,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="debugging.html" title="17. Debugging pools"
<a href="debugging.html" title="18. Debugging pools"
>next</a> |</li>
<li class="right" >
<a href="pattern.html" title="15. Allocation patterns"
<a href="pattern.html" title="16. Allocation patterns"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

187
mps/manual/html/topic/index.html
View file

@ -68,129 +68,130 @@ <h3>Navigation</h3>
<li class="toctree-l2"><a class="reference internal" href="interface.html#general-types">1.9. General types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="error.html">2. Error handing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="error.html#result-codes">2.1. Result codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="error.html#assertions">2.2. Assertions</a></li>
<li class="toctree-l2"><a class="reference internal" href="error.html#common-assertions-and-their-causes">2.3. Common assertions and their causes</a></li>
<li class="toctree-l2"><a class="reference internal" href="error.html#varieties">2.4. Varieties</a></li>
<li class="toctree-l1"><a class="reference internal" href="keyword.html">2. Keyword arguments</a></li>
<li class="toctree-l1"><a class="reference internal" href="error.html">3. Error handing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="error.html#result-codes">3.1. Result codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="error.html#assertions">3.2. Assertions</a></li>
<li class="toctree-l2"><a class="reference internal" href="error.html#common-assertions-and-their-causes">3.3. Common assertions and their causes</a></li>
<li class="toctree-l2"><a class="reference internal" href="error.html#varieties">3.4. Varieties</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="arena.html">3. Arenas</a><ul>
<li class="toctree-l2"><a class="reference internal" href="arena.html#client-arenas">3.1. Client arenas</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#virtual-memory-arenas">3.2. Virtual memory arenas</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#arena-properties">3.3. Arena properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#arena-states">3.4. Arena states</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#running-garbage-collections">3.5. Running garbage collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#using-idle-time-for-collection">3.6. Using idle time for collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#arena-introspection">3.7. Arena introspection</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#protection-interface">3.8. Protection interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="arena.html">4. Arenas</a><ul>
<li class="toctree-l2"><a class="reference internal" href="arena.html#client-arenas">4.1. Client arenas</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#virtual-memory-arenas">4.2. Virtual memory arenas</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#arena-properties">4.3. Arena properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#arena-states">4.4. Arena states</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#running-garbage-collections">4.5. Running garbage collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#using-idle-time-for-collection">4.6. Using idle time for collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#arena-introspection">4.7. Arena introspection</a></li>
<li class="toctree-l2"><a class="reference internal" href="arena.html#protection-interface">4.8. Protection interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="pool.html">4. Pools</a><ul>
<li class="toctree-l2"><a class="reference internal" href="pool.html#pool-classes">4.1. Pool classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="pool.html#pool-introspection">4.2. Pool introspection</a></li>
<li class="toctree-l1"><a class="reference internal" href="pool.html">5. Pools</a><ul>
<li class="toctree-l2"><a class="reference internal" href="pool.html#pool-classes">5.1. Pool classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="pool.html#pool-introspection">5.2. Pool introspection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="allocation.html">5. Allocation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#manual-allocation">5.1. Manual allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#allocation-points">5.2. Allocation points</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#allocation-point-protocol">5.3. Allocation point protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#example-allocating-a-symbol">5.4. Example: allocating a symbol</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#cautions">5.5. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#example-inserting-into-a-doubly-linked-list">5.6. Example: inserting into a doubly linked list</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#allocation-point-implementation">5.7. Allocation point implementation</a></li>
<li class="toctree-l1"><a class="reference internal" href="allocation.html">6. Allocation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#manual-allocation">6.1. Manual allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#allocation-points">6.2. Allocation points</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#allocation-point-protocol">6.3. Allocation point protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#example-allocating-a-symbol">6.4. Example: allocating a symbol</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#cautions">6.5. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#example-inserting-into-a-doubly-linked-list">6.6. Example: inserting into a doubly linked list</a></li>
<li class="toctree-l2"><a class="reference internal" href="allocation.html#allocation-point-implementation">6.7. Allocation point implementation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="format.html">6. Object formats</a><ul>
<li class="toctree-l2"><a class="reference internal" href="format.html#creating-an-object-format">6.1. Creating an object format</a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html#cautions">6.2. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html#format-methods">6.3. Format methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html#object-format-introspection">6.4. Object format introspection</a></li>
<li class="toctree-l1"><a class="reference internal" href="format.html">7. Object formats</a><ul>
<li class="toctree-l2"><a class="reference internal" href="format.html#creating-an-object-format">7.1. Creating an object format</a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html#cautions">7.2. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html#format-methods">7.3. Format methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html#object-format-introspection">7.4. Object format introspection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="scanning.html">7. Scanning</a><ul>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#scanning-protocol">7.1. Scanning protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#tagged-references">7.2. Tagged references</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#critical-path">7.3. Critical path</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#ambiguous-references">7.4. Ambiguous references</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#unfixed-references">7.5. Unfixed references</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#example-scheme-objects">7.6. Example: Scheme objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#scanning-interface">7.7. Scanning interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#fixing-interface">7.8. Fixing interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="scanning.html">8. Scanning</a><ul>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#scanning-protocol">8.1. Scanning protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#tagged-references">8.2. Tagged references</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#critical-path">8.3. Critical path</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#ambiguous-references">8.4. Ambiguous references</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#unfixed-references">8.5. Unfixed references</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#example-scheme-objects">8.6. Example: Scheme objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#scanning-interface">8.7. Scanning interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="scanning.html#fixing-interface">8.8. Fixing interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="thread.html">8. Threads</a><ul>
<li class="toctree-l2"><a class="reference internal" href="thread.html#thread-safety">8.1. Thread safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html#thread-registration">8.2. Thread registration</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html#signal-handling-issues">8.3. Signal handling issues</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html#thread-interface">8.4. Thread interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="thread.html">9. Threads</a><ul>
<li class="toctree-l2"><a class="reference internal" href="thread.html#thread-safety">9.1. Thread safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html#thread-registration">9.2. Thread registration</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html#signal-handling-issues">9.3. Signal handling issues</a></li>
<li class="toctree-l2"><a class="reference internal" href="thread.html#thread-interface">9.4. Thread interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="root.html">9. Roots</a><ul>
<li class="toctree-l2"><a class="reference internal" href="root.html#registering-roots">9.1. Registering roots</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#cautions">9.2. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#thread-roots">9.3. Thread roots</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#ranks">9.4. Ranks</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#root-modes">9.5. Root modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#root-interface">9.6. Root interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#root-introspection">9.7. Root introspection</a></li>
<li class="toctree-l1"><a class="reference internal" href="root.html">10. Roots</a><ul>
<li class="toctree-l2"><a class="reference internal" href="root.html#registering-roots">10.1. Registering roots</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#cautions">10.2. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#thread-roots">10.3. Thread roots</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#ranks">10.4. Ranks</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#root-modes">10.5. Root modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#root-interface">10.6. Root interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="root.html#root-introspection">10.7. Root introspection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="collection.html">10. Garbage collection</a><ul>
<li class="toctree-l2"><a class="reference internal" href="collection.html#generation-chains">10.1. Generation chains</a></li>
<li class="toctree-l2"><a class="reference internal" href="collection.html#scheduling-of-collections">10.2. Scheduling of collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="collection.html#garbage-collection-start-messages">10.3. Garbage collection start messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="collection.html#garbage-collection-messages">10.4. Garbage collection messages</a></li>
<li class="toctree-l1"><a class="reference internal" href="collection.html">11. Garbage collection</a><ul>
<li class="toctree-l2"><a class="reference internal" href="collection.html#generation-chains">11.1. Generation chains</a></li>
<li class="toctree-l2"><a class="reference internal" href="collection.html#scheduling-of-collections">11.2. Scheduling of collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="collection.html#garbage-collection-start-messages">11.3. Garbage collection start messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="collection.html#garbage-collection-messages">11.4. Garbage collection messages</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="message.html">11. Messages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="message.html#finalization-messages">11.1. Finalization messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#example-interactive-chatter">11.2. Example: interactive chatter</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#message-types">11.3. Message types</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#message-interface">11.4. Message interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#message-queue-interface">11.5. Message queue interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="message.html">12. Messages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="message.html#finalization-messages">12.1. Finalization messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#example-interactive-chatter">12.2. Example: interactive chatter</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#message-types">12.3. Message types</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#message-interface">12.4. Message interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html#message-queue-interface">12.5. Message queue interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="finalization.html">12. Finalization</a><ul>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#multiple-finalizations">12.1. Multiple finalizations</a></li>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#cautions">12.2. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#finalization-interface">12.3. Finalization interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#finalization-messages">12.4. Finalization messages</a></li>
<li class="toctree-l1"><a class="reference internal" href="finalization.html">13. Finalization</a><ul>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#multiple-finalizations">13.1. Multiple finalizations</a></li>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#cautions">13.2. Cautions</a></li>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#finalization-interface">13.3. Finalization interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="finalization.html#finalization-messages">13.4. Finalization messages</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="location.html">13. Location dependency</a><ul>
<li class="toctree-l2"><a class="reference internal" href="location.html#terminology">13.1. Terminology</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#creating-dependencies">13.2. Creating dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#adding-dependencies">13.3. Adding dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#testing-dependencies-for-staleness">13.4. Testing dependencies for staleness</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#thread-safety">13.5. Thread safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#location-dependency-interface">13.6. Location dependency interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="location.html">14. Location dependency</a><ul>
<li class="toctree-l2"><a class="reference internal" href="location.html#terminology">14.1. Terminology</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#creating-dependencies">14.2. Creating dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#adding-dependencies">14.3. Adding dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#testing-dependencies-for-staleness">14.4. Testing dependencies for staleness</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#thread-safety">14.5. Thread safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="location.html#location-dependency-interface">14.6. Location dependency interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cache.html">14. Segregated allocation caches</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cache.html#cache-interface">14.1. Cache interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="cache.html#allocation-interface">14.2. Allocation interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="cache.html">15. Segregated allocation caches</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cache.html#cache-interface">15.1. Cache interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="cache.html#allocation-interface">15.2. Allocation interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="pattern.html">15. Allocation patterns</a><ul>
<li class="toctree-l2"><a class="reference internal" href="pattern.html#ramp-allocation">15.1. Ramp allocation</a></li>
<li class="toctree-l1"><a class="reference internal" href="pattern.html">16. Allocation patterns</a><ul>
<li class="toctree-l2"><a class="reference internal" href="pattern.html#ramp-allocation">16.1. Ramp allocation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="frame.html">16. Allocation frames</a></li>
<li class="toctree-l1"><a class="reference internal" href="debugging.html">17. Debugging pools</a></li>
<li class="toctree-l1"><a class="reference internal" href="telemetry.html">18. Telemetry</a><ul>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#telemetry-utilities">18.1. Telemetry utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#example">18.2. Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#event-categories">18.3. Event categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#environment-variables">18.4. Environment variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#decoding-the-telemetry-stream">18.5. Decoding the telemetry stream</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#making-the-telemetry-stream-readable">18.6. Making the telemetry stream readable</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#loading-the-telemetry-stream-into-sqlite">18.7. Loading the telemetry stream into SQLite</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#telemetry-interface">18.8. Telemetry interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#telemetry-labels">18.9. Telemetry labels</a></li>
<li class="toctree-l1"><a class="reference internal" href="frame.html">17. Allocation frames</a></li>
<li class="toctree-l1"><a class="reference internal" href="debugging.html">18. Debugging pools</a></li>
<li class="toctree-l1"><a class="reference internal" href="telemetry.html">19. Telemetry</a><ul>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#telemetry-utilities">19.1. Telemetry utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#example">19.2. Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#event-categories">19.3. Event categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#environment-variables">19.4. Environment variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#decoding-the-telemetry-stream">19.5. Decoding the telemetry stream</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#making-the-telemetry-stream-readable">19.6. Making the telemetry stream readable</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#loading-the-telemetry-stream-into-sqlite">19.7. Loading the telemetry stream into SQLite</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#telemetry-interface">19.8. Telemetry interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="telemetry.html#telemetry-labels">19.9. Telemetry labels</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="weak.html">19. Weak references</a></li>
<li class="toctree-l1"><a class="reference internal" href="weak.html">20. Weak references</a></li>
</ul>
</div>
</div>

21
mps/manual/html/topic/interface.html
View file

@ -28,7 +28,7 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="2. Error handing" href="error.html" />
<link rel="next" title="2. Keyword arguments" href="keyword.html" />
<link rel="prev" title="Reference" href="index.html" />
</head>
<body>
@ -39,7 +39,7 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="error.html" title="2. Error handing"
<a href="keyword.html" title="2. Keyword arguments"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Reference"
@ -89,8 +89,8 @@ <h3>Navigation</h3>
<div class="section" id="language">
<span id="index-2"></span><h2>1.2. Language<a class="headerlink" href="#language" title="Permalink to this headline"></a></h2>
<ol class="arabic simple">
<li>The MPS public interface conforms to ANSI/ISO Standard C (IEC
9899:1990).</li>
<li>The MPS public interface conforms to <a class="reference internal" href="../mmref/bib.html#c1990"><em>ANSI/ISO Standard C (IEC
9899:1990)</em></a>.</li>
</ol>
</div>
<div class="section" id="headers">
@ -177,6 +177,9 @@ <h3>Navigation</h3>
the same as an out parameter except that the location it points to
is read by the function. See for example <a class="reference internal" href="scanning.html#MPS_FIX12" title="MPS_FIX12"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX12()</span></tt></a>.</li>
<li>In/out parameters have names ending with <tt class="docutils literal"><span class="pre">_io</span></tt>.</li>
<li>A function that takes optional arguments does so in the form of an
array of keyword argument structures. These functions have names
ending with <tt class="docutils literal"><span class="pre">_k</span></tt>. See <a class="reference internal" href="keyword.html#topic-keyword"><em>Keyword arguments</em></a>.</li>
</ol>
</div>
<div class="section" id="type-punning">
@ -185,7 +188,7 @@ <h3>Navigation</h3>
out parameter, like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* allocate a struct foo */</span>
<span class="k">struct</span> <span class="n">foo</span> <span class="o">*</span><span class="n">fp</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_alloc</span><span class="p">((</span><span class="kt">mps_addr_t</span> <span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">fp</span><span class="p">,</span> <span class="n">pool</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">foo</span><span class="p">));</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_alloc</span><span class="p">((</span><span class="n">mps_addr_t</span> <span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">fp</span><span class="p">,</span> <span class="n">pool</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">foo</span><span class="p">));</span>
</pre></div>
</div>
<p>This is known as <a class="reference internal" href="../glossary/t.html#term-type-punning"><em class="xref std std-term">type punning</em></a>, and its behaviour is not
@ -194,7 +197,7 @@ <h3>Navigation</h3>
another: the behaviour of this cast is not covered by any of the cases
in the standard.</p>
<p>Instead, we recommend this approach:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_addr_t</span> <span class="n">p</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">foo</span> <span class="o">*</span><span class="n">fp</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_alloc</span><span class="p">(</span><span class="o">&amp;</span><span class="n">p</span><span class="p">,</span> <span class="n">pool</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">foo</span><span class="p">));</span>
<span class="k">if</span><span class="p">(</span><span class="n">res</span><span class="p">)</span> <span class="cm">/* handle error case */</span><span class="p">;</span>
@ -352,8 +355,8 @@ <h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Reference</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="error.html"
title="next chapter">2. Error handing</a></p><h4>Downloads</h4>
<p class="topless"><a href="keyword.html"
title="next chapter">2. Keyword arguments</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -379,7 +382,7 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="error.html" title="2. Error handing"
<a href="keyword.html" title="2. Keyword arguments"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Reference"

369
mps/manual/html/topic/keyword.html Normal file
View file

@ -0,0 +1,369 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>2. Keyword arguments &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.111.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="3. Error handing" href="error.html" />
<link rel="prev" title="1. Interface conventions" href="interface.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="error.html" title="3. Error handing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="interface.html" title="1. Interface conventions"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="keyword-arguments">
<span id="topic-keyword"></span><span id="index-0"></span><h1>2. Keyword arguments<a class="headerlink" href="#keyword-arguments" title="Permalink to this headline"></a></h1>
<p>Some functions in the MPS interface take <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a> in
order to pass values that might be optional, or are only required in
some circumstances. For example, the function
<a class="reference internal" href="arena.html#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> creates any class of <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>, but
<a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client arenas</em></a> require you to specify a base address. These
arguments are passed in a keyword argument array, like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">;</span>
<span class="n">mps_arg_s</span> <span class="n">args</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
<span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">key</span> <span class="o">=</span> <span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">;</span>
<span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">6553600</span><span class="p">;</span>
<span class="n">args</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">key</span> <span class="o">=</span> <span class="n">MPS_KEY_ARENA_CL_ADDR</span><span class="p">;</span>
<span class="n">args</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">val</span><span class="p">.</span><span class="n">addr</span> <span class="o">=</span> <span class="n">base_address</span><span class="p">;</span>
<span class="n">args</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">key</span> <span class="o">=</span> <span class="n">MPS_KEY_ARGS_END</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span> <span class="n">args</span><span class="p">);</span>
</pre></div>
</div>
<p>Each keyword argument in the array is a structure of type
<a class="reference internal" href="#mps_arg_s" title="mps_arg_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_arg_s</span></tt></a>.</p>
<p>For convenience and robustness, the MPS interface includes macros to
help with forming keyword argument lists:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">MPS_ARGS_BEGIN</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="mi">6553600</span><span class="p">);</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_CL_ADDR</span><span class="p">,</span> <span class="n">addr</span><span class="p">,</span> <span class="n">base_address</span><span class="p">);</span>
<span class="n">MPS_ARGS_DONE</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span> <span class="n">args</span><span class="p">);</span>
<span class="p">}</span> <span class="n">MPS_ARGS_END</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
</pre></div>
</div>
<p>But if you are writing <a class="reference internal" href="../glossary/c.html#term-c99"><em class="xref std std-term">C99</em></a>, you can write this more concisely as:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span>
<span class="p">(</span><span class="n">mps_arg_s</span><span class="p">[]){{</span><span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">size</span> <span class="o">=</span> <span class="mi">6553600</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARENA_CL_ADDR</span><span class="p">,</span> <span class="p">.</span><span class="n">val</span><span class="p">.</span><span class="n">addr</span> <span class="o">=</span> <span class="n">base_address</span><span class="p">},</span>
<span class="p">{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}});</span>
</pre></div>
</div>
<p>The argument array must not be <tt class="docutils literal"><span class="pre">NULL</span></tt>, and must end with
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARGS_END</span></tt>. If you don&#8217;t want to pass any arguments, you can
either call the equivalent function that does not take keyword arguments
(named without the <tt class="docutils literal"><span class="pre">_k</span></tt>) or pass <a class="reference internal" href="#mps_args_none" title="mps_args_none"><tt class="xref c c-macro docutils literal"><span class="pre">mps_args_none</span></tt></a>.</p>
<p>When a function that takes keyword arguments returns, the keyword
argument array has been <em>modified</em> to remove any arguments that have
been used. If all arguments have been used, the first element key is
now <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARGS_END</span></tt>.</p>
<dl class="type">
<dt id="mps_arg_s">
<tt class="descname">mps_arg_s</tt><a class="headerlink" href="#mps_arg_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to represent a single
<a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a> to a function.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_arg_s</span> <span class="p">{</span>
<span class="n">mps_key_t</span> <span class="n">key</span><span class="p">;</span>
<span class="k">union</span> <span class="p">{</span>
<span class="n">mps_bool_t</span> <span class="n">b</span><span class="p">;</span>
<span class="kt">char</span> <span class="n">c</span><span class="p">;</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">string</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
<span class="kt">unsigned</span> <span class="n">u</span><span class="p">;</span>
<span class="kt">long</span> <span class="n">l</span><span class="p">;</span>
<span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">ul</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">addr</span><span class="p">;</span>
<span class="n">mps_fmt_t</span> <span class="n">format</span><span class="p">;</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">mps_pool_debug_option_s</span> <span class="o">*</span><span class="n">pool_debug_options</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="p">(</span><span class="o">*</span><span class="n">addr_method</span><span class="p">)(</span><span class="n">mps_addr_t</span><span class="p">);</span>
<span class="n">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="n">mps_word_t</span> <span class="n">count</span><span class="p">;</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">p</span><span class="p">;</span>
<span class="n">mps_rank_t</span> <span class="n">rank</span><span class="p">;</span>
<span class="p">}</span> <span class="n">val</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_arg_s</span><span class="p">;</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">key</span></tt> identifies the key. It must be one of the legal values
of <a class="reference internal" href="#mps_key_t" title="mps_key_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_key_t</span></tt></a> listed in the documentation for that type.</p>
<p><tt class="docutils literal"><span class="pre">val</span></tt> is the corresponding value. The documentation for each
value of the type <a class="reference internal" href="#mps_key_t" title="mps_key_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_key_t</span></tt></a> explains which structure
member is used by that keyword.</p>
</dd></dl>
<dl class="macro">
<dt id="mps_args_none">
<tt class="descname">mps_args_none</tt><a class="headerlink" href="#mps_args_none" title="Permalink to this definition"></a></dt>
<dd><p>An array of <a class="reference internal" href="#mps_arg_s" title="mps_arg_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_arg_s</span></tt></a> representing the empty list of
keyword arguments. Equivalent to:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_arg_s</span> <span class="n">mps_args_none</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{{</span><span class="n">MPS_KEY_ARGS_END</span><span class="p">}};</span>
</pre></div>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_key_t">
<tt class="descname">mps_key_t</tt><a class="headerlink" href="#mps_key_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a> keys. Must take one of the
following values:</p>
<table border="1" class="docutils">
<colgroup>
<col width="19%" />
<col width="10%" />
<col width="71%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Keyword</th>
<th class="head">Value slot</th>
<th class="head">See</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARGS_END</span></tt></td>
<td><em>none</em></td>
<td><em>see above</em></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ALIGN</span></tt></td>
<td><tt class="docutils literal"><span class="pre">align</span></tt></td>
<td><a class="reference internal" href="../pool/mvff.html#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_AMS_SUPPORT_AMBIGUOUS</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span></tt></td>
<td><a class="reference internal" href="../pool/ams.html#mps_class_ams" title="mps_class_ams"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_ams()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_CL_ADDR</span></tt></td>
<td><tt class="docutils literal"><span class="pre">addr</span></tt></td>
<td><a class="reference internal" href="arena.html#mps_arena_class_cl" title="mps_arena_class_cl"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_class_cl()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt></td>
<td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td><a class="reference internal" href="arena.html#mps_arena_class_vm" title="mps_arena_class_vm"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_class_vm()</span></tt></a>, <a class="reference internal" href="arena.html#mps_arena_class_cl" title="mps_arena_class_cl"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_class_cl()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_AWL_FIND_DEPENDENT</span></tt></td>
<td><tt class="docutils literal"><span class="pre">addr_method</span></tt></td>
<td><a class="reference internal" href="../pool/awl.html#mps_class_awl" title="mps_class_awl"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_awl()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_CHAIN</span></tt></td>
<td><tt class="docutils literal"><span class="pre">chain</span></tt></td>
<td><a class="reference internal" href="../pool/amc.html#mps_class_amc" title="mps_class_amc"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_amc()</span></tt></a>, <a class="reference internal" href="../pool/amcz.html#mps_class_amcz" title="mps_class_amcz"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_amcz()</span></tt></a>, <a class="reference internal" href="../pool/ams.html#mps_class_ams" title="mps_class_ams"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_ams()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_EXTEND_BY</span></tt></td>
<td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td><a class="reference internal" href="../pool/mfs.html#mps_class_mfs" title="mps_class_mfs"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mfs()</span></tt></a>, <a class="reference internal" href="../pool/mv.html#mps_class_mv" title="mps_class_mv"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mv()</span></tt></a>, <a class="reference internal" href="../pool/mvff.html#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FORMAT</span></tt></td>
<td><tt class="docutils literal"><span class="pre">format</span></tt></td>
<td><a class="reference internal" href="../pool/amc.html#mps_class_amc" title="mps_class_amc"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_amc()</span></tt></a>, <a class="reference internal" href="../pool/amcz.html#mps_class_amcz" title="mps_class_amcz"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_amcz()</span></tt></a>, <a class="reference internal" href="../pool/ams.html#mps_class_ams" title="mps_class_ams"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_ams()</span></tt></a>, <a class="reference internal" href="../pool/awl.html#mps_class_awl" title="mps_class_awl"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_awl()</span></tt></a>, <a class="reference internal" href="../pool/lo.html#mps_class_lo" title="mps_class_lo"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_lo()</span></tt></a> , <a class="reference internal" href="../pool/snc.html#mps_class_snc" title="mps_class_snc"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_snc()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MAX_SIZE</span></tt></td>
<td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td><a class="reference internal" href="../pool/mv.html#mps_class_mv" title="mps_class_mv"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mv()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MEAN_SIZE</span></tt></td>
<td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td><a class="reference internal" href="../pool/mv.html#mps_class_mv" title="mps_class_mv"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mv()</span></tt></a>, <a class="reference internal" href="../pool/mvt.html#mps_class_mvt" title="mps_class_mvt"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvt()</span></tt></a>, <a class="reference internal" href="../pool/mvff.html#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MFS_UNIT_SIZE</span></tt></td>
<td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td><a class="reference internal" href="../pool/mfs.html#mps_class_mfs" title="mps_class_mfs"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mfs()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MIN_SIZE</span></tt></td>
<td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td><a class="reference internal" href="../pool/mvt.html#mps_class_mvt" title="mps_class_mvt"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvt()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_ARENA_HIGH</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span></tt></td>
<td><a class="reference internal" href="../pool/mvff.html#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_FIRST_FIT</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span></tt></td>
<td><a class="reference internal" href="../pool/mvff.html#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVFF_SLOT_HIGH</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span></tt></td>
<td><a class="reference internal" href="../pool/mvff.html#mps_class_mvff" title="mps_class_mvff"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVT_FRAG_LIMIT</span></tt></td>
<td><tt class="docutils literal"><span class="pre">count</span></tt></td>
<td><a class="reference internal" href="../pool/mvt.html#mps_class_mvt" title="mps_class_mvt"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvt()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_MVT_RESERVE_DEPTH</span></tt></td>
<td><tt class="docutils literal"><span class="pre">count</span></tt></td>
<td><a class="reference internal" href="../pool/mvt.html#mps_class_mvt" title="mps_class_mvt"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvt()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_POOL_DEBUG_OPTIONS</span></tt></td>
<td><tt class="docutils literal"><span class="pre">pool_debug_options</span></tt></td>
<td><a class="reference internal" href="../pool/ams.html#mps_class_ams_debug" title="mps_class_ams_debug"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_ams_debug()</span></tt></a>, <a class="reference internal" href="../pool/mv.html#mps_class_mv_debug" title="mps_class_mv_debug"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mv_debug()</span></tt></a>, <a class="reference internal" href="../pool/mvff.html#mps_class_mvff_debug" title="mps_class_mvff_debug"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff_debug()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_RANK</span></tt></td>
<td><tt class="docutils literal"><span class="pre">rank</span></tt></td>
<td><a class="reference internal" href="../pool/awl.html#mps_class_awl" title="mps_class_awl"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_awl()</span></tt></a>, <a class="reference internal" href="../pool/snc.html#mps_class_snc" title="mps_class_snc"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_snc()</span></tt></a></td>
</tr>
<tr class="row-even"><td><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_VMW3_TOP_DOWN</span></tt></td>
<td><tt class="docutils literal"><span class="pre">b</span></tt></td>
<td><a class="reference internal" href="arena.html#mps_arena_class_vm" title="mps_arena_class_vm"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_class_vm()</span></tt></a></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="MPS_ARGS_BEGIN">
<tt class="descname">MPS_ARGS_BEGIN</tt><big>(</big>args<big>)</big><a class="headerlink" href="#MPS_ARGS_BEGIN" title="Permalink to this definition"></a></dt>
<dd><p>Start construction of a list of keyword arguments. This macro must
be used like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">MPS_ARGS_BEGIN</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="mi">6553600</span><span class="p">);</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_CL_ADDR</span><span class="p">,</span> <span class="n">addr</span><span class="p">,</span> <span class="n">base_address</span><span class="p">);</span>
<span class="n">MPS_ARGS_DONE</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span> <span class="n">args</span><span class="p">);</span>
<span class="p">}</span> <span class="n">MPS_ARGS_END</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
</pre></div>
</div>
<p>That is, you must call <a class="reference internal" href="#MPS_ARGS_ADD" title="MPS_ARGS_ADD"><tt class="xref c c-func docutils literal"><span class="pre">MPS_ARGS_ADD()</span></tt></a> zero or more times,
and then call <a class="reference internal" href="#MPS_ARGS_DONE" title="MPS_ARGS_DONE"><tt class="xref c c-func docutils literal"><span class="pre">MPS_ARGS_DONE()</span></tt></a> before passing the arguments
to a function.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> is the name of the array that contains the keyword
arguments. The array is stack-allocated, and exists between
<a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_BEGIN</span></tt></a> and <a class="reference internal" href="#MPS_ARGS_END" title="MPS_ARGS_END"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_END</span></tt></a>.</p>
<p>It is safe to nest blocks created by <a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_BEGIN</span></tt></a> and
<a class="reference internal" href="#MPS_ARGS_END" title="MPS_ARGS_END"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_END</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="MPS_ARGS_ADD">
<tt class="descname">MPS_ARGS_ADD</tt><big>(</big><a class="reference internal" href="#mps_arg_s" title="mps_arg_s">mps_arg_s</a><em>&nbsp;args[]</em>, <a class="reference internal" href="#mps_key_t" title="mps_key_t">mps_key_t</a><em>&nbsp;key</em>, value<big>)</big><a class="headerlink" href="#MPS_ARGS_ADD" title="Permalink to this definition"></a></dt>
<dd><p>Add an argument to a list of keyword arguments. This macro must be
used only between <a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_BEGIN</span></tt></a> and
<a class="reference internal" href="#MPS_ARGS_END" title="MPS_ARGS_END"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_END</span></tt></a>.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> is the name of array that contains the keyword arguments.
It must match the argument to the preceding call to
<a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_ARGS_BEGIN()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="MPS_ARGS_DONE">
<tt class="descname">MPS_ARGS_DONE</tt><big>(</big>args<big>)</big><a class="headerlink" href="#MPS_ARGS_DONE" title="Permalink to this definition"></a></dt>
<dd><p>Finalize a list of keyword arguments. This macro must be used only
between <a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_BEGIN</span></tt></a> and <a class="reference internal" href="#MPS_ARGS_END" title="MPS_ARGS_END"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_ARGS_END</span></tt></a>.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> is the name of array that contains the keyword arguments.
It must match the argument to the preceding call to
<a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_ARGS_BEGIN()</span></tt></a>.</p>
<p>After calling this macro, the array <tt class="docutils literal"><span class="pre">args</span></tt> is ready to pass to a
function.</p>
</dd></dl>
<dl class="function">
<dt id="MPS_ARGS_END">
<tt class="descname">MPS_ARGS_END</tt><big>(</big>args<big>)</big><a class="headerlink" href="#MPS_ARGS_END" title="Permalink to this definition"></a></dt>
<dd><p>Finish using a list of keyword arguments whose construction was
started by <a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_ARGS_BEGIN()</span></tt></a>.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> is the name of array that contains the keyword arguments.
It must match the argument to the preceding call to
<a class="reference internal" href="#MPS_ARGS_BEGIN" title="MPS_ARGS_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_ARGS_BEGIN()</span></tt></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.png" alt="Logo"/>
</a></p>
<h4>Previous topic</h4>
<p class="topless"><a href="interface.html"
title="previous chapter">1. Interface conventions</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="error.html"
title="next chapter">3. Error handing</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
<a href="http://www.ravenbrook.com/project/mps/release/">All MPS Kit releases</a>
</p>
<h4>Issues</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/issue/?action=list&amp;view=status%3dopen&amp;display=Job:Priority:Title&amp;sort=Priority">Known issues</a><br>
<a href="http://www.ravenbrook.com/project/mps/issue/?action=fixed&release_fixed=1.111.0">Issues fixed in release 1.111.0</a>
</p><h4>Contact us</h4>
<p class="topless"><a href="mailto:mps-questions@ravenbrook.com">mps-questions@ravenbrook.com</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="error.html" title="3. Error handing"
>next</a> |</li>
<li class="right" >
<a href="interface.html" title="1. Interface conventions"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2013, Ravenbrook Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>

64
mps/manual/html/topic/location.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>13. Location dependency &mdash; Memory Pool System 1.111.0 documentation</title>
<title>14. Location dependency &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="14. Segregated allocation caches" href="cache.html" />
<link rel="prev" title="12. Finalization" href="finalization.html" />
<link rel="next" title="15. Segregated allocation caches" href="cache.html" />
<link rel="prev" title="13. Finalization" href="finalization.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="cache.html" title="14. Segregated allocation caches"
<a href="cache.html" title="15. Segregated allocation caches"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="finalization.html" title="12. Finalization"
<a href="finalization.html" title="13. Finalization"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="location-dependency">
<span id="topic-location"></span><span id="index-0"></span><h1>13. Location dependency<a class="headerlink" href="#location-dependency" title="Permalink to this headline"></a></h1>
<span id="topic-location"></span><span id="index-0"></span><h1>14. Location dependency<a class="headerlink" href="#location-dependency" title="Permalink to this headline"></a></h1>
<p>Location dependencies provide a means by which the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> can depend on the <em class="dfn">location</em> of blocks (that is, on the
bits in pointers to the blocks) in the presence of a <a class="reference internal" href="../glossary/m.html#term-moving-memory-manager"><em class="xref std std-term">moving
@ -66,7 +66,7 @@ <h3>Navigation</h3>
See the section <a class="reference internal" href="../guide/advanced.html#guide-advanced-location"><em>Location dependency</em></a> in the Guide for a more
detailed look at this example.</p>
<div class="section" id="terminology">
<h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline"></a></h2>
<h2>14.1. Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline"></a></h2>
<p>A <em class="dfn">location dependency</em> is represented by an structure of type
<a class="reference internal" href="#mps_ld_s" title="mps_ld_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_ld_s</span></tt></a>. It encapsulates a set of dependencies on the
locations of blocks. It can be used to determine whether any of the
@ -85,7 +85,7 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
moved since the respective dependency was made.</p>
</div>
<div class="section" id="creating-dependencies">
<span id="index-1"></span><h2>13.2. Creating dependencies<a class="headerlink" href="#creating-dependencies" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>14.2. Creating dependencies<a class="headerlink" href="#creating-dependencies" title="Permalink to this headline"></a></h2>
<p>The <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> must provide space for the
<a class="reference internal" href="#mps_ld_s" title="mps_ld_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_ld_s</span></tt></a> structure. Typically, this will be inlined in some
larger structure. This structure can be in memory managed by the MPS
@ -93,11 +93,11 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
<p>For example, the toy Scheme interpreter inlines the location
dependency in its hash table structure:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">table_s</span> <span class="p">{</span>
<span class="kt">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_TABLE */</span>
<span class="kt">hash_t</span> <span class="n">hash</span><span class="p">;</span> <span class="cm">/* hash function */</span>
<span class="kt">cmp_t</span> <span class="n">cmp</span><span class="p">;</span> <span class="cm">/* comparison function */</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_TABLE */</span>
<span class="n">hash_t</span> <span class="n">hash</span><span class="p">;</span> <span class="cm">/* hash function */</span>
<span class="n">cmp_t</span> <span class="n">cmp</span><span class="p">;</span> <span class="cm">/* comparison function */</span>
<span class="hll"> <span class="n">mps_ld_s</span> <span class="n">ld</span><span class="p">;</span> <span class="cm">/* location dependency */</span>
</span> <span class="kt">obj_t</span> <span class="n">buckets</span><span class="p">;</span> <span class="cm">/* hash buckets */</span>
</span> <span class="n">obj_t</span> <span class="n">buckets</span><span class="p">;</span> <span class="cm">/* hash buckets */</span>
<span class="p">}</span> <span class="n">table_s</span><span class="p">;</span>
</pre></div>
</div>
@ -113,7 +113,7 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
whenever <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> returns true.</p>
</div>
<div class="section" id="adding-dependencies">
<span id="index-2"></span><h2>13.3. Adding dependencies<a class="headerlink" href="#adding-dependencies" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>14.3. Adding dependencies<a class="headerlink" href="#adding-dependencies" title="Permalink to this headline"></a></h2>
<p><em>Before</em> the location of a block is depended on (for example,
hashed) a reference to the block may be added to a location
dependency by calling <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>. Dependencies on many
@ -125,18 +125,18 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
that is added to the table must be added to the dependency before its
address is hashed. In the toy Scheme interpreter this is most easily
done in the function that hashes an address:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eq_hash</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eq_hash</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="n">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">union</span> <span class="p">{</span><span class="kt">char</span> <span class="n">s</span><span class="p">[</span><span class="k">sizeof</span><span class="p">(</span><span class="kt">obj_t</span><span class="p">)];</span> <span class="kt">obj_t</span> <span class="n">addr</span><span class="p">;}</span> <span class="n">u</span><span class="p">;</span>
<span class="k">union</span> <span class="p">{</span><span class="kt">char</span> <span class="n">s</span><span class="p">[</span><span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">)];</span> <span class="n">obj_t</span> <span class="n">addr</span><span class="p">;}</span> <span class="n">u</span><span class="p">;</span>
<span class="hll"> <span class="k">if</span> <span class="p">(</span><span class="n">ld</span><span class="p">)</span> <span class="n">mps_ld_add</span><span class="p">(</span><span class="n">ld</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">obj</span><span class="p">);</span>
</span> <span class="n">u</span><span class="p">.</span><span class="n">addr</span> <span class="o">=</span> <span class="n">obj</span><span class="p">;</span>
<span class="k">return</span> <span class="n">hash</span><span class="p">(</span><span class="n">u</span><span class="p">.</span><span class="n">s</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">obj_t</span><span class="p">));</span>
<span class="k">return</span> <span class="n">hash</span><span class="p">(</span><span class="n">u</span><span class="p">.</span><span class="n">s</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="testing-dependencies-for-staleness">
<span id="index-3"></span><h2>13.4. Testing dependencies for staleness<a class="headerlink" href="#testing-dependencies-for-staleness" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>14.4. Testing dependencies for staleness<a class="headerlink" href="#testing-dependencies-for-staleness" title="Permalink to this headline"></a></h2>
<p>When the locations of blocks are used (during a hash table lookup for
example), the computation should be carried out and the result used in
the usual way (for example, the pointer is hashed and the has used to
@ -168,7 +168,7 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
</ol>
<p>For example, in the case of a hash table you should rehash based on
the new locations of the blocks.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">obj_t</span> <span class="nf">table_ref</span><span class="p">(</span><span class="kt">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="kt">obj_t</span> <span class="n">key</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">table_ref</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">key</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">struct</span> <span class="n">bucket_s</span> <span class="o">*</span><span class="n">b</span> <span class="o">=</span> <span class="n">buckets_find</span><span class="p">(</span><span class="n">tbl</span><span class="p">,</span> <span class="n">tbl</span><span class="o">-&gt;</span><span class="n">table</span><span class="p">.</span><span class="n">buckets</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">b</span> <span class="o">&amp;&amp;</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">key</span> <span class="o">!=</span> <span class="nb">NULL</span> <span class="o">&amp;&amp;</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">key</span> <span class="o">!=</span> <span class="n">obj_deleted</span><span class="p">)</span>
@ -195,7 +195,7 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
and return it.</p>
</div>
<div class="section" id="thread-safety">
<span id="index-4"></span><h2>13.5. Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>14.5. Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline"></a></h2>
<p>The functions are all thread-safe with respect to operations on
different location dependencies. That means that it is not necessary
for threads to interlock if they are performing operations on
@ -204,7 +204,7 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
need to access the same location dependency.</p>
</div>
<div class="section" id="location-dependency-interface">
<span id="index-5"></span><h2>13.6. Location dependency interface<a class="headerlink" href="#location-dependency-interface" title="Permalink to this headline"></a></h2>
<span id="index-5"></span><h2>14.6. Location dependency interface<a class="headerlink" href="#location-dependency-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_ld_t">
<tt class="descname">mps_ld_t</tt><a class="headerlink" href="#mps_ld_t" title="Permalink to this definition"></a></dt>
@ -229,7 +229,7 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
<dd><p>The type of the structure used to represent a <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location
dependency</em></a>.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_ld_s</span> <span class="p">{</span>
<span class="kt">mps_word_t</span> <span class="n">w0</span><span class="p">,</span> <span class="n">w1</span><span class="p">;</span>
<span class="n">mps_word_t</span> <span class="n">w0</span><span class="p">,</span> <span class="n">w1</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_ld_s</span><span class="p">;</span>
</pre></div>
</div>
@ -353,23 +353,23 @@ <h2>13.1. Terminology<a class="headerlink" href="#terminology" title="Permalink
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">13. Location dependency</a><ul>
<li><a class="reference internal" href="#terminology">13.1. Terminology</a></li>
<li><a class="reference internal" href="#creating-dependencies">13.2. Creating dependencies</a></li>
<li><a class="reference internal" href="#adding-dependencies">13.3. Adding dependencies</a></li>
<li><a class="reference internal" href="#testing-dependencies-for-staleness">13.4. Testing dependencies for staleness</a></li>
<li><a class="reference internal" href="#thread-safety">13.5. Thread safety</a></li>
<li><a class="reference internal" href="#location-dependency-interface">13.6. Location dependency interface</a></li>
<li><a class="reference internal" href="#">14. Location dependency</a><ul>
<li><a class="reference internal" href="#terminology">14.1. Terminology</a></li>
<li><a class="reference internal" href="#creating-dependencies">14.2. Creating dependencies</a></li>
<li><a class="reference internal" href="#adding-dependencies">14.3. Adding dependencies</a></li>
<li><a class="reference internal" href="#testing-dependencies-for-staleness">14.4. Testing dependencies for staleness</a></li>
<li><a class="reference internal" href="#thread-safety">14.5. Thread safety</a></li>
<li><a class="reference internal" href="#location-dependency-interface">14.6. Location dependency interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="finalization.html"
title="previous chapter">12. Finalization</a></p>
title="previous chapter">13. Finalization</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="cache.html"
title="next chapter">14. Segregated allocation caches</a></p><h4>Downloads</h4>
title="next chapter">15. Segregated allocation caches</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -395,10 +395,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="cache.html" title="14. Segregated allocation caches"
<a href="cache.html" title="15. Segregated allocation caches"
>next</a> |</li>
<li class="right" >
<a href="finalization.html" title="12. Finalization"
<a href="finalization.html" title="13. Finalization"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

48
mps/manual/html/topic/message.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>11. Messages &mdash; Memory Pool System 1.111.0 documentation</title>
<title>12. Messages &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="12. Finalization" href="finalization.html" />
<link rel="prev" title="10. Garbage collection" href="collection.html" />
<link rel="next" title="13. Finalization" href="finalization.html" />
<link rel="prev" title="11. Garbage collection" href="collection.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="finalization.html" title="12. Finalization"
<a href="finalization.html" title="13. Finalization"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="collection.html" title="10. Garbage collection"
<a href="collection.html" title="11. Garbage collection"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="messages">
<span id="topic-message"></span><span id="index-0"></span><h1>11. Messages<a class="headerlink" href="#messages" title="Permalink to this headline"></a></h1>
<span id="topic-message"></span><span id="index-0"></span><h1>12. Messages<a class="headerlink" href="#messages" title="Permalink to this headline"></a></h1>
<p>The MPS sometimes needs to communicate with the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>
about events which occur <a class="reference internal" href="../glossary/a.html#term-asynchronous-garbage-collector"><em class="xref std std-term">asynchronously</em></a>, and so information cannot be returned as function call
results.</p>
@ -79,7 +79,7 @@ <h3>Navigation</h3>
garbage collections no longer start until some of these messages are
retrieved and discarded.</p>
<div class="section" id="finalization-messages">
<span id="index-1"></span><h2>11.1. Finalization messages<a class="headerlink" href="#finalization-messages" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>12.1. Finalization messages<a class="headerlink" href="#finalization-messages" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">Finalization</em></a> is implemented by posting a finalization message
(of type <a class="reference internal" href="finalization.html#mps_message_type_finalization" title="mps_message_type_finalization"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_finalization()</span></tt></a>) to the arena&#8217;s
message queue. This allows the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> to perform the
@ -91,7 +91,7 @@ <h3>Navigation</h3>
<p>See <a class="reference internal" href="finalization.html#topic-finalization"><em>Finalization</em></a>.</p>
</div>
<div class="section" id="example-interactive-chatter">
<span id="index-2"></span><h2>11.2. Example: interactive chatter<a class="headerlink" href="#example-interactive-chatter" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>12.2. Example: interactive chatter<a class="headerlink" href="#example-interactive-chatter" title="Permalink to this headline"></a></h2>
<p>The toy Scheme interpreter enables garbage collection messages when
started in interactive mode:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_message_type_enable</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_message_type_gc</span><span class="p">());</span>
@ -103,11 +103,11 @@ <h3>Navigation</h3>
contents of each one:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">mps_chat</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">mps_message_type_t</span> <span class="n">type</span><span class="p">;</span>
<span class="n">mps_message_type_t</span> <span class="n">type</span><span class="p">;</span>
<span class="k">while</span> <span class="p">(</span><span class="n">mps_message_queue_type</span><span class="p">(</span><span class="o">&amp;</span><span class="n">type</span><span class="p">,</span> <span class="n">arena</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">mps_message_t</span> <span class="n">message</span><span class="p">;</span>
<span class="kt">mps_bool_t</span> <span class="n">b</span><span class="p">;</span>
<span class="n">mps_message_t</span> <span class="n">message</span><span class="p">;</span>
<span class="n">mps_bool_t</span> <span class="n">b</span><span class="p">;</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">mps_message_get</span><span class="p">(</span><span class="o">&amp;</span><span class="n">message</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">type</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">b</span><span class="p">);</span> <span class="cm">/* we just checked there was one */</span>
@ -165,7 +165,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="message-types">
<span id="index-3"></span><h2>11.3. Message types<a class="headerlink" href="#message-types" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>12.3. Message types<a class="headerlink" href="#message-types" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_message_type_t">
<tt class="descname">mps_message_type_t</tt><a class="headerlink" href="#mps_message_type_t" title="Permalink to this definition"></a></dt>
@ -221,7 +221,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="message-interface">
<span id="index-4"></span><h2>11.4. Message interface<a class="headerlink" href="#message-interface" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>12.4. Message interface<a class="headerlink" href="#message-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_message_t">
<tt class="descname">mps_message_t</tt><a class="headerlink" href="#mps_message_t" title="Permalink to this definition"></a></dt>
@ -297,7 +297,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="message-queue-interface">
<span id="index-5"></span><h2>11.5. Message queue interface<a class="headerlink" href="#message-queue-interface" title="Permalink to this headline"></a></h2>
<span id="index-5"></span><h2>12.5. Message queue interface<a class="headerlink" href="#message-queue-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_message_get">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_message_get</tt><big>(</big><a class="reference internal" href="#mps_message_t" title="mps_message_t">mps_message_t</a><em>&nbsp;*message_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a><em>&nbsp;message_type</em><big>)</big><a class="headerlink" href="#mps_message_get" title="Permalink to this definition"></a></dt>
@ -362,22 +362,22 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">11. Messages</a><ul>
<li><a class="reference internal" href="#finalization-messages">11.1. Finalization messages</a></li>
<li><a class="reference internal" href="#example-interactive-chatter">11.2. Example: interactive chatter</a></li>
<li><a class="reference internal" href="#message-types">11.3. Message types</a></li>
<li><a class="reference internal" href="#message-interface">11.4. Message interface</a></li>
<li><a class="reference internal" href="#message-queue-interface">11.5. Message queue interface</a></li>
<li><a class="reference internal" href="#">12. Messages</a><ul>
<li><a class="reference internal" href="#finalization-messages">12.1. Finalization messages</a></li>
<li><a class="reference internal" href="#example-interactive-chatter">12.2. Example: interactive chatter</a></li>
<li><a class="reference internal" href="#message-types">12.3. Message types</a></li>
<li><a class="reference internal" href="#message-interface">12.4. Message interface</a></li>
<li><a class="reference internal" href="#message-queue-interface">12.5. Message queue interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="collection.html"
title="previous chapter">10. Garbage collection</a></p>
title="previous chapter">11. Garbage collection</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="finalization.html"
title="next chapter">12. Finalization</a></p><h4>Downloads</h4>
title="next chapter">13. Finalization</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -403,10 +403,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="finalization.html" title="12. Finalization"
<a href="finalization.html" title="13. Finalization"
>next</a> |</li>
<li class="right" >
<a href="collection.html" title="10. Garbage collection"
<a href="collection.html" title="11. Garbage collection"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

26
mps/manual/html/topic/pattern.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>15. Allocation patterns &mdash; Memory Pool System 1.111.0 documentation</title>
<title>16. Allocation patterns &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="16. Allocation frames" href="frame.html" />
<link rel="prev" title="14. Segregated allocation caches" href="cache.html" />
<link rel="next" title="17. Allocation frames" href="frame.html" />
<link rel="prev" title="15. Segregated allocation caches" href="cache.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="frame.html" title="16. Allocation frames"
<a href="frame.html" title="17. Allocation frames"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="cache.html" title="14. Segregated allocation caches"
<a href="cache.html" title="15. Segregated allocation caches"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="allocation-patterns">
<span id="topic-pattern"></span><span id="index-0"></span><h1>15. Allocation patterns<a class="headerlink" href="#allocation-patterns" title="Permalink to this headline"></a></h1>
<span id="topic-pattern"></span><span id="index-0"></span><h1>16. Allocation patterns<a class="headerlink" href="#allocation-patterns" title="Permalink to this headline"></a></h1>
<p>An <em class="dfn">allocation pattern</em> is a hint to the MPS to expect a
particular pattern of allocation on an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a>. The
MPS may use this hint to schedule more effective garbage collection.</p>
@ -129,7 +129,7 @@ <h3>Navigation</h3>
</dd></dl>
<div class="section" id="ramp-allocation">
<span id="topic-pattern-ramp"></span><span id="index-1"></span><h2>15.1. Ramp allocation<a class="headerlink" href="#ramp-allocation" title="Permalink to this headline"></a></h2>
<span id="topic-pattern-ramp"></span><span id="index-1"></span><h2>16.1. Ramp allocation<a class="headerlink" href="#ramp-allocation" title="Permalink to this headline"></a></h2>
<p><em class="dfn">Ramp allocation</em> a pattern of allocation whereby the
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> builds up an increasingly large data structure,
the live size of which increases until a particular time, at which
@ -187,18 +187,18 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">15. Allocation patterns</a><ul>
<li><a class="reference internal" href="#ramp-allocation">15.1. Ramp allocation</a></li>
<li><a class="reference internal" href="#">16. Allocation patterns</a><ul>
<li><a class="reference internal" href="#ramp-allocation">16.1. Ramp allocation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="cache.html"
title="previous chapter">14. Segregated allocation caches</a></p>
title="previous chapter">15. Segregated allocation caches</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="frame.html"
title="next chapter">16. Allocation frames</a></p><h4>Downloads</h4>
title="next chapter">17. Allocation frames</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -224,10 +224,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="frame.html" title="16. Allocation frames"
<a href="frame.html" title="17. Allocation frames"
>next</a> |</li>
<li class="right" >
<a href="cache.html" title="14. Segregated allocation caches"
<a href="cache.html" title="15. Segregated allocation caches"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

4
mps/manual/html/topic/plinth.html
View file

@ -218,13 +218,13 @@ <h3>Navigation</h3>
instance, with <tt class="docutils literal"><span class="pre">getrusage()</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &lt;sys/resource.h&gt;</span>
<span class="kt">mps_clock_t</span> <span class="nf">mps_clock</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="n">mps_clock_t</span> <span class="nf">mps_clock</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="k">struct</span> <span class="n">rusage</span> <span class="n">s</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">res</span> <span class="o">=</span> <span class="n">getrusage</span><span class="p">(</span><span class="n">RUSAGE_SELF</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">s</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* handle error */</span>
<span class="p">}</span>
<span class="k">return</span> <span class="p">((</span><span class="kt">mps_clock_t</span><span class="p">)</span><span class="n">s</span><span class="p">.</span><span class="n">ru_utime</span><span class="p">.</span><span class="n">tv_sec</span><span class="p">)</span> <span class="o">*</span> <span class="mi">1000000</span> <span class="o">+</span> <span class="n">s</span><span class="p">.</span><span class="n">ru_utime</span><span class="p">.</span><span class="n">tv_usec</span><span class="p">;</span>
<span class="k">return</span> <span class="p">((</span><span class="n">mps_clock_t</span><span class="p">)</span><span class="n">s</span><span class="p">.</span><span class="n">ru_utime</span><span class="p">.</span><span class="n">tv_sec</span><span class="p">)</span> <span class="o">*</span> <span class="mi">1000000</span> <span class="o">+</span> <span class="n">s</span><span class="p">.</span><span class="n">ru_utime</span><span class="p">.</span><span class="n">tv_usec</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>

65
mps/manual/html/topic/pool.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>4. Pools &mdash; Memory Pool System 1.111.0 documentation</title>
<title>5. Pools &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="5. Allocation" href="allocation.html" />
<link rel="prev" title="3. Arenas" href="arena.html" />
<link rel="next" title="6. Allocation" href="allocation.html" />
<link rel="prev" title="4. Arenas" href="arena.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="allocation.html" title="5. Allocation"
<a href="allocation.html" title="6. Allocation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="arena.html" title="3. Arenas"
<a href="arena.html" title="4. Arenas"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="pools">
<span id="topic-pool"></span><span id="index-0"></span><h1>4. Pools<a class="headerlink" href="#pools" title="Permalink to this headline"></a></h1>
<span id="topic-pool"></span><span id="index-0"></span><h1>5. Pools<a class="headerlink" href="#pools" title="Permalink to this headline"></a></h1>
<p>Within an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> a client program creates one or more pools. A
pool is responsible for requesting memory from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> and
making it available for allocation.</p>
@ -70,31 +70,46 @@ <h3>Navigation</h3>
<dl class="function">
<dt id="mps_pool_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, ...<big>)</big><a class="headerlink" href="#mps_pool_create" title="Permalink to this definition"></a></dt>
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, <a class="reference internal" href="keyword.html#mps_arg_s" title="mps_arg_s">mps_arg_s</a><em>&nbsp;args[]</em><big>)</big><a class="headerlink" href="#mps_pool_create" title="Permalink to this definition"></a></dt>
<dd><p>Create a <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> in an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">pool_o</span></tt> points to a location that will hold a pointer to the new
pool.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena in which to create the pool.</p>
<p><tt class="docutils literal"><span class="pre">class</span></tt> is the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> of the new pool.</p>
<p>Some pool classes require additional arguments to be passed to
<a class="reference internal" href="#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>. See the documentation for the pool
class.</p>
<p><tt class="docutils literal"><span class="pre">args</span></tt> are <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a> specific to the pool class.
See the documentation for the pool class.</p>
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the pool is created successfully,
or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> otherwise.</p>
<p>The pool persists until it is destroyed by calling
<a class="reference internal" href="#mps_pool_destroy" title="mps_pool_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_destroy()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">There&#8217;s an alternative function <tt class="xref c c-func docutils literal"><span class="pre">pool_create_v()</span></tt> that
takes its extra arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
<tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
</dd></dl>
<dl class="function">
<dt>
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, ...<big>)</big></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> that takes its
extra arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> variable argument
list mechanism.</p>
</dd></dl>
<dl class="function">
<dt id="mps_pool_create_v">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create_v</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, va_list<em>&nbsp;args</em><big>)</big><a class="headerlink" href="#mps_pool_create_v" title="Permalink to this definition"></a></dt>
<dd><p>An alternative to <a class="reference internal" href="#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> that takes its extra
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt> that takes its extra
arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> <tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
</dd></dl>
@ -114,7 +129,7 @@ <h3>Navigation</h3>
</dd></dl>
<div class="section" id="pool-classes">
<span id="index-1"></span><h2>4.1. Pool classes<a class="headerlink" href="#pool-classes" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>5.1. Pool classes<a class="headerlink" href="#pool-classes" title="Permalink to this headline"></a></h2>
<p>Pools belong to <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> that specify policies for how
their memory is managed. Some pools are <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually managed</em></a> (you must call <a class="reference internal" href="allocation.html#mps_free" title="mps_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_free()</span></tt></a> to
return a block of memory to the pool) and others are
@ -134,7 +149,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="pool-introspection">
<span id="index-2"></span><h2>4.2. Pool introspection<a class="headerlink" href="#pool-introspection" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>5.2. Pool introspection<a class="headerlink" href="#pool-introspection" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_addr_pool">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_addr_pool</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#mps_addr_pool" title="Permalink to this definition"></a></dt>
@ -178,19 +193,19 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">4. Pools</a><ul>
<li><a class="reference internal" href="#pool-classes">4.1. Pool classes</a></li>
<li><a class="reference internal" href="#pool-introspection">4.2. Pool introspection</a></li>
<li><a class="reference internal" href="#">5. Pools</a><ul>
<li><a class="reference internal" href="#pool-classes">5.1. Pool classes</a></li>
<li><a class="reference internal" href="#pool-introspection">5.2. Pool introspection</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="arena.html"
title="previous chapter">3. Arenas</a></p>
title="previous chapter">4. Arenas</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="allocation.html"
title="next chapter">5. Allocation</a></p><h4>Downloads</h4>
title="next chapter">6. Allocation</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -216,10 +231,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="allocation.html" title="5. Allocation"
<a href="allocation.html" title="6. Allocation"
>next</a> |</li>
<li class="right" >
<a href="arena.html" title="3. Arenas"
<a href="arena.html" title="4. Arenas"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

66
mps/manual/html/topic/root.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>9. Roots &mdash; Memory Pool System 1.111.0 documentation</title>
<title>10. Roots &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="10. Garbage collection" href="collection.html" />
<link rel="prev" title="8. Threads" href="thread.html" />
<link rel="next" title="11. Garbage collection" href="collection.html" />
<link rel="prev" title="9. Threads" href="thread.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="collection.html" title="10. Garbage collection"
<a href="collection.html" title="11. Garbage collection"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="thread.html" title="8. Threads"
<a href="thread.html" title="9. Threads"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="roots">
<span id="topic-root"></span><span id="index-0"></span><h1>9. Roots<a class="headerlink" href="#roots" title="Permalink to this headline"></a></h1>
<span id="topic-root"></span><span id="index-0"></span><h1>10. Roots<a class="headerlink" href="#roots" title="Permalink to this headline"></a></h1>
<p><a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">Roots</em></a> tell the <a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a> where to start
<a class="reference internal" href="../glossary/t.html#term-trace"><em class="xref std std-term">tracing</em></a>. The garbage collector determines which blocks
are <a class="reference internal" href="../glossary/r.html#term-reachable"><em class="xref std std-term">reachable</em></a> from the roots, and (in <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically
@ -70,7 +70,7 @@ <h3>Navigation</h3>
is more flexible, but requires the client program to declare which
references are roots.</p>
<div class="section" id="registering-roots">
<span id="index-1"></span><h2>9.1. Registering roots<a class="headerlink" href="#registering-roots" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>10.1. Registering roots<a class="headerlink" href="#registering-roots" title="Permalink to this headline"></a></h2>
<p>You can register a root at any time by calling one of the
<tt class="docutils literal"><span class="pre">mps_root_create</span></tt> functions. Roots may not be registered twice, and
no two roots may overlap (that is, each reference is <a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fixed</em></a> by
@ -129,7 +129,7 @@ <h3>Navigation</h3>
</ol>
</div>
<div class="section" id="cautions">
<span id="index-2"></span><h2>9.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>10.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<p>Creating a root and then registering is similar to reserving a block
and then committing it (in the
<a class="reference internal" href="allocation.html#topic-allocation-point-protocol"><em>Allocation point protocol</em></a>), and similar <a class="reference internal" href="allocation.html#topic-allocation-cautions"><em>cautions</em></a> apply. Before registering a root:</p>
@ -152,7 +152,7 @@ <h3>Navigation</h3>
</ol>
</div>
<div class="section" id="thread-roots">
<span id="topic-root-thread"></span><span id="index-3"></span><h2>9.3. Thread roots<a class="headerlink" href="#thread-roots" title="Permalink to this headline"></a></h2>
<span id="topic-root-thread"></span><span id="index-3"></span><h2>10.3. Thread roots<a class="headerlink" href="#thread-roots" title="Permalink to this headline"></a></h2>
<p>Every thread&#8217;s registers and control stack potentially contain
references to allocated objects, so should be registered as a root by
calling <a class="reference internal" href="#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a>. It&#8217;s not easy to write a
@ -168,8 +168,8 @@ <h3>Navigation</h3>
the stack frame below any potential roots.</p>
<p id="index-4">For example, here&#8217;s the code from the toy Scheme interpreter that
registers a thread root and then calls the program:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_thr_t</span> <span class="kr">thread</span><span class="p">;</span>
<span class="kt">mps_root_t</span> <span class="n">reg_root</span><span class="p">;</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_thr_t</span> <span class="kr">thread</span><span class="p">;</span>
<span class="n">mps_root_t</span> <span class="n">reg_root</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">exit_code</span><span class="p">;</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">marker</span> <span class="o">=</span> <span class="o">&amp;</span><span class="n">marker</span><span class="p">;</span>
@ -194,7 +194,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="ranks">
<span id="index-5"></span><h2>9.4. Ranks<a class="headerlink" href="#ranks" title="Permalink to this headline"></a></h2>
<span id="index-5"></span><h2>10.4. Ranks<a class="headerlink" href="#ranks" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_rank_t">
<tt class="descname">mps_rank_t</tt><a class="headerlink" href="#mps_rank_t" title="Permalink to this definition"></a></dt>
@ -222,7 +222,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="root-modes">
<span id="index-6"></span><h2>9.5. Root modes<a class="headerlink" href="#root-modes" title="Permalink to this headline"></a></h2>
<span id="index-6"></span><h2>10.5. Root modes<a class="headerlink" href="#root-modes" title="Permalink to this headline"></a></h2>
<p>The root mode provides a way for the client to declare various facts
about a root that allow the MPS to make optimizations. Roots that are
declared to be <em>constant</em> need not be re-scanned, and roots that are
@ -291,7 +291,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="root-interface">
<span id="index-7"></span><h2>9.6. Root interface<a class="headerlink" href="#root-interface" title="Permalink to this headline"></a></h2>
<span id="index-7"></span><h2>10.6. Root interface<a class="headerlink" href="#root-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_root_t">
<tt class="descname">mps_root_t</tt><a class="headerlink" href="#mps_root_t" title="Permalink to this definition"></a></dt>
@ -499,17 +499,17 @@ <h3>Navigation</h3>
<span class="cm">/* Global symbol table. */</span>
<span class="kt">size_t</span> <span class="n">symtab_size</span><span class="p">;</span>
<span class="k">struct</span> <span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">symbol</span><span class="p">;</span>
<span class="kt">obj_t</span> <span class="n">value</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">symbol</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">value</span><span class="p">;</span>
<span class="p">}</span> <span class="o">*</span><span class="n">symtab</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="kt">mps_root_t</span> <span class="n">root</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">mps_root_t</span> <span class="n">root</span><span class="p">;</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create_table_masked</span><span class="p">(</span><span class="o">&amp;</span><span class="n">root</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_rank_exact</span><span class="p">(),</span>
<span class="p">(</span><span class="kt">mps_rm_t</span><span class="p">)</span><span class="mi">0</span><span class="p">,</span>
<span class="p">(</span><span class="n">mps_rm_t</span><span class="p">)</span><span class="mi">0</span><span class="p">,</span>
<span class="n">symtab</span><span class="p">,</span> <span class="n">symtab_size</span> <span class="o">*</span> <span class="mi">2</span><span class="p">,</span>
<span class="p">(</span><span class="kt">mps_word_t</span><span class="p">)</span><span class="n">TAG_MASK</span><span class="p">);</span>
<span class="p">(</span><span class="n">mps_word_t</span><span class="p">)</span><span class="n">TAG_MASK</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">errror</span><span class="p">(</span><span class="s">&quot;can&#39;t create symtab root&quot;</span><span class="p">);</span>
</pre></div>
</div>
@ -524,7 +524,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="root-introspection">
<span id="index-8"></span><h2>9.7. Root introspection<a class="headerlink" href="#root-introspection" title="Permalink to this headline"></a></h2>
<span id="index-8"></span><h2>10.7. Root introspection<a class="headerlink" href="#root-introspection" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_arena_roots_walk">
void <tt class="descname">mps_arena_roots_walk</tt><big>(</big><a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_roots_stepper_t" title="mps_roots_stepper_t">mps_roots_stepper_t</a><em>&nbsp;f</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;s</em><big>)</big><a class="headerlink" href="#mps_arena_roots_walk" title="Permalink to this definition"></a></dt>
@ -598,24 +598,24 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">9. Roots</a><ul>
<li><a class="reference internal" href="#registering-roots">9.1. Registering roots</a></li>
<li><a class="reference internal" href="#cautions">9.2. Cautions</a></li>
<li><a class="reference internal" href="#thread-roots">9.3. Thread roots</a></li>
<li><a class="reference internal" href="#ranks">9.4. Ranks</a></li>
<li><a class="reference internal" href="#root-modes">9.5. Root modes</a></li>
<li><a class="reference internal" href="#root-interface">9.6. Root interface</a></li>
<li><a class="reference internal" href="#root-introspection">9.7. Root introspection</a></li>
<li><a class="reference internal" href="#">10. Roots</a><ul>
<li><a class="reference internal" href="#registering-roots">10.1. Registering roots</a></li>
<li><a class="reference internal" href="#cautions">10.2. Cautions</a></li>
<li><a class="reference internal" href="#thread-roots">10.3. Thread roots</a></li>
<li><a class="reference internal" href="#ranks">10.4. Ranks</a></li>
<li><a class="reference internal" href="#root-modes">10.5. Root modes</a></li>
<li><a class="reference internal" href="#root-interface">10.6. Root interface</a></li>
<li><a class="reference internal" href="#root-introspection">10.7. Root introspection</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="thread.html"
title="previous chapter">8. Threads</a></p>
title="previous chapter">9. Threads</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="collection.html"
title="next chapter">10. Garbage collection</a></p><h4>Downloads</h4>
title="next chapter">11. Garbage collection</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -641,10 +641,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="collection.html" title="10. Garbage collection"
<a href="collection.html" title="11. Garbage collection"
>next</a> |</li>
<li class="right" >
<a href="thread.html" title="8. Threads"
<a href="thread.html" title="9. Threads"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

72
mps/manual/html/topic/scanning.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>7. Scanning &mdash; Memory Pool System 1.111.0 documentation</title>
<title>8. Scanning &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="8. Threads" href="thread.html" />
<link rel="prev" title="6. Object formats" href="format.html" />
<link rel="next" title="9. Threads" href="thread.html" />
<link rel="prev" title="7. Object formats" href="format.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="thread.html" title="8. Threads"
<a href="thread.html" title="9. Threads"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="format.html" title="6. Object formats"
<a href="format.html" title="7. Object formats"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="scanning">
<span id="topic-scanning"></span><span id="index-0"></span><h1>7. Scanning<a class="headerlink" href="#scanning" title="Permalink to this headline"></a></h1>
<span id="topic-scanning"></span><span id="index-0"></span><h1>8. Scanning<a class="headerlink" href="#scanning" title="Permalink to this headline"></a></h1>
<p><a class="reference internal" href="../glossary/s.html#term-scan"><em class="xref std std-term">Scanning</em></a> is the process of identifying the
<a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> in a block of memory and
<a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">&#8220;fixing&#8221;</em></a> them. It&#8217;s the process at the heart of the
@ -69,7 +69,7 @@ <h3>Navigation</h3>
these objects. Both tasks use the same scanning protocol, described
here.</p>
<div class="section" id="scanning-protocol">
<span id="topic-scanning-protocol"></span><span id="index-1"></span><h2>7.1. Scanning protocol<a class="headerlink" href="#scanning-protocol" title="Permalink to this headline"></a></h2>
<span id="topic-scanning-protocol"></span><span id="index-1"></span><h2>8.1. Scanning protocol<a class="headerlink" href="#scanning-protocol" title="Permalink to this headline"></a></h2>
<p>There are several types of scanning functions (the <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a>
in an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>, of type <a class="reference internal" href="format.html#mps_fmt_scan_t" title="mps_fmt_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_scan_t</span></tt></a>, and
root scanning functions of various types) but all take a <a class="reference internal" href="../glossary/s.html#term-scan-state"><em class="xref std std-term">scan
@ -101,7 +101,7 @@ <h3>Navigation</h3>
details, which are covered in the following sections.</p>
</div>
<div class="section" id="tagged-references">
<span id="topic-scanning-tag"></span><span id="index-2"></span><h2>7.2. Tagged references<a class="headerlink" href="#tagged-references" title="Permalink to this headline"></a></h2>
<span id="topic-scanning-tag"></span><span id="index-2"></span><h2>8.2. Tagged references<a class="headerlink" href="#tagged-references" title="Permalink to this headline"></a></h2>
<p>If your references are <a class="reference internal" href="../glossary/t.html#term-tagged-reference"><em class="xref std std-term">tagged</em></a> (or otherwise
&#8220;encrypted&#8221;), then you must remove the tag (or decrypt them) before
passing them to <a class="reference internal" href="#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a> and <a class="reference internal" href="#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a>.</p>
@ -121,12 +121,12 @@ <h3>Navigation</h3>
might look like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">MPS_FIX1</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span><span class="p">))</span> <span class="p">{</span>
<span class="cm">/* strip the tag */</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span> <span class="o">&amp;</span> <span class="o">~</span><span class="mh">0x7</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="n">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span> <span class="o">&amp;</span> <span class="o">~</span><span class="mh">0x7</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="k">return</span> <span class="n">res</span><span class="p">;</span>
<span class="cm">/* restore the tag and update reference */</span>
<span class="kt">mps_word_t</span> <span class="n">tag</span> <span class="o">=</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span> <span class="o">&amp;</span> <span class="mh">0x7</span><span class="p">;</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span> <span class="o">=</span> <span class="p">(</span><span class="kt">obj_t</span><span class="p">)((</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span><span class="n">p</span> <span class="o">+</span> <span class="n">tag</span><span class="p">);</span>
<span class="n">mps_word_t</span> <span class="n">tag</span> <span class="o">=</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span> <span class="o">&amp;</span> <span class="mh">0x7</span><span class="p">;</span>
<span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span> <span class="o">=</span> <span class="p">(</span><span class="n">obj_t</span><span class="p">)((</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span><span class="n">p</span> <span class="o">+</span> <span class="n">tag</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
@ -138,7 +138,7 @@ <h3>Navigation</h3>
belongs to an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> of variant auto-header).</p>
</div>
<div class="section" id="critical-path">
<span id="index-3"></span><h2>7.3. Critical path<a class="headerlink" href="#critical-path" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>8.3. Critical path<a class="headerlink" href="#critical-path" title="Permalink to this headline"></a></h2>
<p>Scanning is an operation on the critical path of the MPS and so it is
vital that it runs fast. The scanning protocol is designed to ensure
that as much of the scanning code can be run inline in the client
@ -176,7 +176,7 @@ <h3>Navigation</h3>
objects do not need to be scanned at all.</p>
</div>
<div class="section" id="ambiguous-references">
<span id="index-4"></span><h2>7.4. Ambiguous references<a class="headerlink" href="#ambiguous-references" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>8.4. Ambiguous references<a class="headerlink" href="#ambiguous-references" title="Permalink to this headline"></a></h2>
<p>If the references in the object being scanned are <a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous</em></a> then <a class="reference internal" href="#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a> does not update the
reference (because it can&#8217;t know if it&#8217;s a genuine reference). The MPS
handles an ambiguous reference by <a class="reference internal" href="../glossary/p.html#term-pinning"><em class="xref std std-term">pinning</em></a> the block pointed to
@ -193,7 +193,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="unfixed-references">
<span id="index-5"></span><h2>7.5. Unfixed references<a class="headerlink" href="#unfixed-references" title="Permalink to this headline"></a></h2>
<span id="index-5"></span><h2>8.5. Unfixed references<a class="headerlink" href="#unfixed-references" title="Permalink to this headline"></a></h2>
<p>The MPS does not require you to <a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fix</em></a> all your <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a>. But if a reference is not fixed:</p>
<ol class="arabic simple">
<li>it does not keep its target alive (this might be acceptable if you
@ -212,7 +212,7 @@ <h3>Navigation</h3>
references.</p>
</div>
<div class="section" id="example-scheme-objects">
<span id="index-6"></span><h2>7.6. Example: Scheme objects<a class="headerlink" href="#example-scheme-objects" title="Permalink to this headline"></a></h2>
<span id="index-6"></span><h2>8.6. Example: Scheme objects<a class="headerlink" href="#example-scheme-objects" title="Permalink to this headline"></a></h2>
<p>Scanning tends to be a repetitive procedure and so you&#8217;ll find it is
usually helpful to define macros to reduce the size of the source
code. The MPS provides a convenience macro <a class="reference internal" href="#MPS_FIX12" title="MPS_FIX12"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX12()</span></tt></a> for the
@ -244,11 +244,11 @@ <h3>Navigation</h3>
is not defined by the C standard. See <a class="reference internal" href="interface.html#topic-interface-pun"><em>Type punning</em></a>.</p>
</div>
<p>Here&#8217;s the Scheme scanner:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">while</span> <span class="p">(</span><span class="n">base</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="k">switch</span> <span class="p">(</span><span class="n">obj</span><span class="o">-&gt;</span><span class="n">type</span><span class="p">.</span><span class="n">type</span><span class="p">)</span> <span class="p">{</span>
<span class="k">case</span> <span class="n">TYPE_PAIR</span>:
<span class="n">FIX</span><span class="p">(</span><span class="n">obj</span><span class="o">-&gt;</span><span class="n">pair</span><span class="p">.</span><span class="n">car</span><span class="p">);</span>
@ -285,7 +285,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="scanning-interface">
<span id="index-7"></span><h2>7.7. Scanning interface<a class="headerlink" href="#scanning-interface" title="Permalink to this headline"></a></h2>
<span id="index-7"></span><h2>8.7. Scanning interface<a class="headerlink" href="#scanning-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_ss_t">
<tt class="descname">mps_ss_t</tt><a class="headerlink" href="#mps_ss_t" title="Permalink to this definition"></a></dt>
@ -366,10 +366,10 @@ <h3>Navigation</h3>
<tt class="docutils literal"><span class="pre">data_scan</span></tt>. In order to ensure that the scan state is passed
correctly to <tt class="docutils literal"><span class="pre">data_scan</span></tt>, the call must be wrapped in
<a class="reference internal" href="#MPS_FIX_CALL" title="MPS_FIX_CALL"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX_CALL()</span></tt></a>.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="kt">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span><span class="p">;</span>
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span> <span class="n">obj</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">;</span> <span class="n">obj</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">MPS_FIX12</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">obj</span><span class="o">-&gt;</span><span class="n">left</span><span class="p">)</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span>
@ -395,7 +395,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="fixing-interface">
<span id="index-8"></span><h2>7.8. Fixing interface<a class="headerlink" href="#fixing-interface" title="Permalink to this headline"></a></h2>
<span id="index-8"></span><h2>8.8. Fixing interface<a class="headerlink" href="#fixing-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="MPS_FIX1">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">MPS_FIX1</tt><big>(</big><a class="reference internal" href="#mps_ss_t" title="mps_ss_t">mps_ss_t</a><em>&nbsp;ss</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;ref</em><big>)</big><a class="headerlink" href="#MPS_FIX1" title="Permalink to this definition"></a></dt>
@ -508,25 +508,25 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">7. Scanning</a><ul>
<li><a class="reference internal" href="#scanning-protocol">7.1. Scanning protocol</a></li>
<li><a class="reference internal" href="#tagged-references">7.2. Tagged references</a></li>
<li><a class="reference internal" href="#critical-path">7.3. Critical path</a></li>
<li><a class="reference internal" href="#ambiguous-references">7.4. Ambiguous references</a></li>
<li><a class="reference internal" href="#unfixed-references">7.5. Unfixed references</a></li>
<li><a class="reference internal" href="#example-scheme-objects">7.6. Example: Scheme objects</a></li>
<li><a class="reference internal" href="#scanning-interface">7.7. Scanning interface</a></li>
<li><a class="reference internal" href="#fixing-interface">7.8. Fixing interface</a></li>
<li><a class="reference internal" href="#">8. Scanning</a><ul>
<li><a class="reference internal" href="#scanning-protocol">8.1. Scanning protocol</a></li>
<li><a class="reference internal" href="#tagged-references">8.2. Tagged references</a></li>
<li><a class="reference internal" href="#critical-path">8.3. Critical path</a></li>
<li><a class="reference internal" href="#ambiguous-references">8.4. Ambiguous references</a></li>
<li><a class="reference internal" href="#unfixed-references">8.5. Unfixed references</a></li>
<li><a class="reference internal" href="#example-scheme-objects">8.6. Example: Scheme objects</a></li>
<li><a class="reference internal" href="#scanning-interface">8.7. Scanning interface</a></li>
<li><a class="reference internal" href="#fixing-interface">8.8. Fixing interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="format.html"
title="previous chapter">6. Object formats</a></p>
title="previous chapter">7. Object formats</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="thread.html"
title="next chapter">8. Threads</a></p><h4>Downloads</h4>
title="next chapter">9. Threads</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -552,10 +552,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="thread.html" title="8. Threads"
<a href="thread.html" title="9. Threads"
>next</a> |</li>
<li class="right" >
<a href="format.html" title="6. Object formats"
<a href="format.html" title="7. Object formats"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

58
mps/manual/html/topic/telemetry.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>18. Telemetry &mdash; Memory Pool System 1.111.0 documentation</title>
<title>19. Telemetry &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="19. Weak references" href="weak.html" />
<link rel="prev" title="17. Debugging pools" href="debugging.html" />
<link rel="next" title="20. Weak references" href="weak.html" />
<link rel="prev" title="18. Debugging pools" href="debugging.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="weak.html" title="19. Weak references"
<a href="weak.html" title="20. Weak references"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="debugging.html" title="17. Debugging pools"
<a href="debugging.html" title="18. Debugging pools"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="telemetry">
<span id="topic-telemetry"></span><h1>18. Telemetry<a class="headerlink" href="#telemetry" title="Permalink to this headline"></a></h1>
<span id="topic-telemetry"></span><h1>19. Telemetry<a class="headerlink" href="#telemetry" title="Permalink to this headline"></a></h1>
<p>In its <a class="reference internal" href="../glossary/c.html#term-cool"><em class="xref std std-term">cool</em></a> and <a class="reference internal" href="../glossary/h.html#term-hot"><em class="xref std std-term">hot</em></a> <a class="reference internal" href="../glossary/v.html#term-variety"><em class="xref std std-term">varieties</em></a>, the MPS is
capable of outputting a configurable stream of events to assist with
debugging and profiling.</p>
@ -93,7 +93,7 @@ <h3>Navigation</h3>
thought we were victims of a practical joker.</p>
</div></blockquote>
<div class="section" id="telemetry-utilities">
<span id="index-2"></span><h2>18.1. Telemetry utilities<a class="headerlink" href="#telemetry-utilities" title="Permalink to this headline"></a></h2>
<span id="index-2"></span><h2>19.1. Telemetry utilities<a class="headerlink" href="#telemetry-utilities" title="Permalink to this headline"></a></h2>
<p>The telemetry system relies on three utility programs:</p>
<ul class="simple">
<li><a class="reference internal" href="#telemetry-mpseventcnv"><em>mpseventcnv</em></a> decodes the
@ -111,7 +111,7 @@ <h3>Navigation</h3>
<a class="reference internal" href="../guide/build.html#guide-build"><em>Building the Memory Pool System</em></a>. Thee programs are described in more detail below.</p>
</div>
<div class="section" id="example">
<span id="index-3"></span><h2>18.2. Example<a class="headerlink" href="#example" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>19.2. Example<a class="headerlink" href="#example" title="Permalink to this headline"></a></h2>
<p>Here&#8217;s an example of turning on telemetry in the debugger and then
encountering a corrupted object:</p>
<div class="highlight-none"><div class="highlight"><pre>$ gdb ./scheme
@ -190,7 +190,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="event-categories">
<span id="index-4"></span><h2>18.3. Event categories<a class="headerlink" href="#event-categories" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>19.3. Event categories<a class="headerlink" href="#event-categories" title="Permalink to this headline"></a></h2>
<p>The &#8220;bit&#8221; column gives the bit number in the <a class="reference internal" href="../glossary/t.html#term-telemetry-filter"><em class="xref std std-term">telemetry filter</em></a>.
These numbers are liable to change, but the current meanings (zero
being the least significant bit) are:</p>
@ -239,7 +239,7 @@ <h3>Navigation</h3>
</table>
</div>
<div class="section" id="environment-variables">
<span id="index-5"></span><h2>18.4. Environment variables<a class="headerlink" href="#environment-variables" title="Permalink to this headline"></a></h2>
<span id="index-5"></span><h2>19.4. Environment variables<a class="headerlink" href="#environment-variables" title="Permalink to this headline"></a></h2>
<p>In the ANSI <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> (the plinth that comes as default with the
MPS), these two environment variables control the behaviour of the
telemetry feature.</p>
@ -285,7 +285,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="decoding-the-telemetry-stream">
<span id="telemetry-mpseventcnv"></span><span id="index-6"></span><h2>18.5. Decoding the telemetry stream<a class="headerlink" href="#decoding-the-telemetry-stream" title="Permalink to this headline"></a></h2>
<span id="telemetry-mpseventcnv"></span><span id="index-6"></span><h2>19.5. Decoding the telemetry stream<a class="headerlink" href="#decoding-the-telemetry-stream" title="Permalink to this headline"></a></h2>
<p>The MPS writes the telemetry stream in a binary encoded format for
speed. The encoding is specific to the platform the program was
running on, and so the output needs to be decoded before it can be
@ -328,7 +328,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="making-the-telemetry-stream-readable">
<span id="telemetry-mpseventtxt"></span><span id="index-7"></span><h2>18.6. Making the telemetry stream readable<a class="headerlink" href="#making-the-telemetry-stream-readable" title="Permalink to this headline"></a></h2>
<span id="telemetry-mpseventtxt"></span><span id="index-7"></span><h2>19.6. Making the telemetry stream readable<a class="headerlink" href="#making-the-telemetry-stream-readable" title="Permalink to this headline"></a></h2>
<p>The output of <a class="reference internal" href="#telemetry-mpseventcnv"><em>mpseventcnv</em></a> can be made
more readable by passing it through <strong class="program">mpseventtxt</strong>, which
takes the following options:</p>
@ -360,7 +360,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="loading-the-telemetry-stream-into-sqlite">
<span id="telemetry-mpseventsql"></span><span id="index-8"></span><h2>18.7. Loading the telemetry stream into SQLite<a class="headerlink" href="#loading-the-telemetry-stream-into-sqlite" title="Permalink to this headline"></a></h2>
<span id="telemetry-mpseventsql"></span><span id="index-8"></span><h2>19.7. Loading the telemetry stream into SQLite<a class="headerlink" href="#loading-the-telemetry-stream-into-sqlite" title="Permalink to this headline"></a></h2>
<p>The decoded telemetry stream (as output by <a class="reference internal" href="#telemetry-mpseventcnv"><em>mpseventcnv</em></a>) can be loaded into a SQLite database for
further analysis by running <strong class="program">mpseventsql</strong>.</p>
<p><strong class="program">mpseventsql</strong> takes the following options:</p>
@ -431,7 +431,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="telemetry-interface">
<span id="index-10"></span><h2>18.8. Telemetry interface<a class="headerlink" href="#telemetry-interface" title="Permalink to this headline"></a></h2>
<span id="index-10"></span><h2>19.8. Telemetry interface<a class="headerlink" href="#telemetry-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_telemetry_control">
<a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a> <tt class="descname">mps_telemetry_control</tt><big>(</big><a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a><em>&nbsp;reset_mask</em>, <a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a><em>&nbsp;flip_mask</em><big>)</big><a class="headerlink" href="#mps_telemetry_control" title="Permalink to this definition"></a></dt>
@ -528,7 +528,7 @@ <h3>Navigation</h3>
</div>
<div class="section" id="telemetry-labels">
<span id="index-11"></span><h2>18.9. Telemetry labels<a class="headerlink" href="#telemetry-labels" title="Permalink to this headline"></a></h2>
<span id="index-11"></span><h2>19.9. Telemetry labels<a class="headerlink" href="#telemetry-labels" title="Permalink to this headline"></a></h2>
<p>Telemetry labels allow the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> to associate strings
with addresses in the telemetry stream. The string must first be
<em>interned</em> by calling <a class="reference internal" href="#mps_telemetry_intern" title="mps_telemetry_intern"><tt class="xref c c-func docutils literal"><span class="pre">mps_telemetry_intern()</span></tt></a>, returning a
@ -613,26 +613,26 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">18. Telemetry</a><ul>
<li><a class="reference internal" href="#telemetry-utilities">18.1. Telemetry utilities</a></li>
<li><a class="reference internal" href="#example">18.2. Example</a></li>
<li><a class="reference internal" href="#event-categories">18.3. Event categories</a></li>
<li><a class="reference internal" href="#environment-variables">18.4. Environment variables</a></li>
<li><a class="reference internal" href="#decoding-the-telemetry-stream">18.5. Decoding the telemetry stream</a></li>
<li><a class="reference internal" href="#making-the-telemetry-stream-readable">18.6. Making the telemetry stream readable</a></li>
<li><a class="reference internal" href="#loading-the-telemetry-stream-into-sqlite">18.7. Loading the telemetry stream into SQLite</a></li>
<li><a class="reference internal" href="#telemetry-interface">18.8. Telemetry interface</a></li>
<li><a class="reference internal" href="#telemetry-labels">18.9. Telemetry labels</a></li>
<li><a class="reference internal" href="#">19. Telemetry</a><ul>
<li><a class="reference internal" href="#telemetry-utilities">19.1. Telemetry utilities</a></li>
<li><a class="reference internal" href="#example">19.2. Example</a></li>
<li><a class="reference internal" href="#event-categories">19.3. Event categories</a></li>
<li><a class="reference internal" href="#environment-variables">19.4. Environment variables</a></li>
<li><a class="reference internal" href="#decoding-the-telemetry-stream">19.5. Decoding the telemetry stream</a></li>
<li><a class="reference internal" href="#making-the-telemetry-stream-readable">19.6. Making the telemetry stream readable</a></li>
<li><a class="reference internal" href="#loading-the-telemetry-stream-into-sqlite">19.7. Loading the telemetry stream into SQLite</a></li>
<li><a class="reference internal" href="#telemetry-interface">19.8. Telemetry interface</a></li>
<li><a class="reference internal" href="#telemetry-labels">19.9. Telemetry labels</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="debugging.html"
title="previous chapter">17. Debugging pools</a></p>
title="previous chapter">18. Debugging pools</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="weak.html"
title="next chapter">19. Weak references</a></p><h4>Downloads</h4>
title="next chapter">20. Weak references</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -658,10 +658,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="weak.html" title="19. Weak references"
<a href="weak.html" title="20. Weak references"
>next</a> |</li>
<li class="right" >
<a href="debugging.html" title="17. Debugging pools"
<a href="debugging.html" title="18. Debugging pools"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

38
mps/manual/html/topic/thread.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>8. Threads &mdash; Memory Pool System 1.111.0 documentation</title>
<title>9. Threads &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -28,8 +28,8 @@
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="9. Roots" href="root.html" />
<link rel="prev" title="7. Scanning" href="scanning.html" />
<link rel="next" title="10. Roots" href="root.html" />
<link rel="prev" title="8. Scanning" href="scanning.html" />
</head>
<body>
<div class="related">
@ -39,10 +39,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="root.html" title="9. Roots"
<a href="root.html" title="10. Roots"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="scanning.html" title="7. Scanning"
<a href="scanning.html" title="8. Scanning"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,9 +55,9 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="threads">
<span id="topic-thread"></span><span id="index-0"></span><h1>8. Threads<a class="headerlink" href="#threads" title="Permalink to this headline"></a></h1>
<span id="topic-thread"></span><span id="index-0"></span><h1>9. Threads<a class="headerlink" href="#threads" title="Permalink to this headline"></a></h1>
<div class="section" id="thread-safety">
<span id="index-1"></span><h2>8.1. Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline"></a></h2>
<span id="index-1"></span><h2>9.1. Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline"></a></h2>
<p>The MPS is designed to run in an environment with multiple threads all
calling into the MPS. Some code is known to operate with exclusive
access to the data it manipulates (for example, allocation via
@ -70,7 +70,7 @@ <h3>Navigation</h3>
time.</p>
</div>
<div class="section" id="thread-registration">
<span id="topic-thread-register"></span><span id="index-2"></span><h2>8.2. Thread registration<a class="headerlink" href="#thread-registration" title="Permalink to this headline"></a></h2>
<span id="topic-thread-register"></span><span id="index-2"></span><h2>9.2. Thread registration<a class="headerlink" href="#thread-registration" title="Permalink to this headline"></a></h2>
<p>In order to scan a thread&#8217;s registers for references (which happens at
each <a class="reference internal" href="../glossary/f.html#term-flip"><em class="xref std std-term">flip</em></a>), the MPS needs to be able to suspend that thread,
and in order to gain exclusive atomic access to memory in order to
@ -100,7 +100,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="signal-handling-issues">
<span id="index-3"></span><h2>8.3. Signal handling issues<a class="headerlink" href="#signal-handling-issues" title="Permalink to this headline"></a></h2>
<span id="index-3"></span><h2>9.3. Signal handling issues<a class="headerlink" href="#signal-handling-issues" title="Permalink to this headline"></a></h2>
<p>The MPS uses <a class="reference internal" href="../glossary/b.html#term-barrier-1"><em class="xref std std-term">barriers<sup>(1)</sup></em></a> to <a class="reference internal" href="../glossary/p.html#term-protection"><em class="xref std std-term">protect</em></a>
memory from the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> and handles the signals that
result from barrier hits.</p>
@ -115,7 +115,7 @@ <h3>Navigation</h3>
</div>
</div>
<div class="section" id="thread-interface">
<span id="index-4"></span><h2>8.4. Thread interface<a class="headerlink" href="#thread-interface" title="Permalink to this headline"></a></h2>
<span id="index-4"></span><h2>9.4. Thread interface<a class="headerlink" href="#thread-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_thr_t">
<tt class="descname">mps_thr_t</tt><a class="headerlink" href="#mps_thr_t" title="Permalink to this definition"></a></dt>
@ -223,21 +223,21 @@ <h3>Navigation</h3>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">8. Threads</a><ul>
<li><a class="reference internal" href="#thread-safety">8.1. Thread safety</a></li>
<li><a class="reference internal" href="#thread-registration">8.2. Thread registration</a></li>
<li><a class="reference internal" href="#signal-handling-issues">8.3. Signal handling issues</a></li>
<li><a class="reference internal" href="#thread-interface">8.4. Thread interface</a></li>
<li><a class="reference internal" href="#">9. Threads</a><ul>
<li><a class="reference internal" href="#thread-safety">9.1. Thread safety</a></li>
<li><a class="reference internal" href="#thread-registration">9.2. Thread registration</a></li>
<li><a class="reference internal" href="#signal-handling-issues">9.3. Signal handling issues</a></li>
<li><a class="reference internal" href="#thread-interface">9.4. Thread interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="scanning.html"
title="previous chapter">7. Scanning</a></p>
title="previous chapter">8. Scanning</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="root.html"
title="next chapter">9. Roots</a></p><h4>Downloads</h4>
title="next chapter">10. Roots</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
@ -263,10 +263,10 @@ <h3>Navigation</h3>
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="root.html" title="9. Roots"
<a href="root.html" title="10. Roots"
>next</a> |</li>
<li class="right" >
<a href="scanning.html" title="7. Scanning"
<a href="scanning.html" title="8. Scanning"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>

20
mps/manual/html/topic/weak.html
View file

@ -8,7 +8,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>19. Weak references &mdash; Memory Pool System 1.111.0 documentation</title>
<title>20. Weak references &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -29,7 +29,7 @@
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="Pool reference" href="../pool/index.html" />
<link rel="prev" title="18. Telemetry" href="telemetry.html" />
<link rel="prev" title="19. Telemetry" href="telemetry.html" />
</head>
<body>
<div class="related">
@ -42,7 +42,7 @@ <h3>Navigation</h3>
<a href="../pool/index.html" title="Pool reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="telemetry.html" title="18. Telemetry"
<a href="telemetry.html" title="19. Telemetry"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
@ -55,7 +55,7 @@ <h3>Navigation</h3>
<div class="body">
<div class="section" id="weak-references">
<span id="topic-weak"></span><span id="index-0"></span><h1>19. Weak references<a class="headerlink" href="#weak-references" title="Permalink to this headline"></a></h1>
<span id="topic-weak"></span><span id="index-0"></span><h1>20. Weak references<a class="headerlink" href="#weak-references" title="Permalink to this headline"></a></h1>
<p>A <em class="dfn">weak reference</em> is a <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a> that does not keep the
block it refers to <a class="reference internal" href="../glossary/l.html#term-live"><em class="xref std std-term">alive</em></a>.</p>
<p>The open source MPS supports weak references only:</p>
@ -78,14 +78,14 @@ <h3>Navigation</h3>
reclaimed.</p>
<p>For example, a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> for objects in an AWL pool might
look like this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="kt">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="kt">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="nf">obj_scan</span><span class="p">(</span><span class="n">mps_ss_t</span> <span class="n">ss</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">limit</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">MPS_SCAN_BEGIN</span><span class="p">(</span><span class="n">ss</span><span class="p">)</span> <span class="p">{</span>
<span class="k">while</span> <span class="p">(</span><span class="n">base</span> <span class="o">&lt;</span> <span class="n">limit</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="kt">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span><span class="p">;</span>
<span class="n">obj_t</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">base</span><span class="p">;</span>
<span class="n">mps_addr_t</span> <span class="n">p</span> <span class="o">=</span> <span class="n">obj</span><span class="o">-&gt;</span><span class="n">ref</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">MPS_FIX1</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="n">p</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="n">mps_res_t</span> <span class="n">res</span> <span class="o">=</span> <span class="n">MPS_FIX2</span><span class="p">(</span><span class="n">ss</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">p</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="k">return</span> <span class="n">res</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">p</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* reference was splatted */</span>
@ -141,7 +141,7 @@ <h3>Navigation</h3>
</a></p>
<h4>Previous topic</h4>
<p class="topless"><a href="telemetry.html"
title="previous chapter">18. Telemetry</a></p>
title="previous chapter">19. Telemetry</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../pool/index.html"
title="next chapter">Pool reference</a></p><h4>Downloads</h4>
@ -173,7 +173,7 @@ <h3>Navigation</h3>
<a href="../pool/index.html" title="Pool reference"
>next</a> |</li>
<li class="right" >
<a href="telemetry.html" title="18. Telemetry"
<a href="telemetry.html" title="19. Telemetry"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>