mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-03-26 16:51:46 -07:00
Code Issues Projects Releases Wiki Activity

Deprecate mps_formatted_objects_walk and mps_amc_apply.

Browse source
This commit is contained in:
Gareth Rees 2020-08-31 14:14:31 +01:00
parent 359bd5b034
commit efff4ea400
8 changed files with 181 additions and 168 deletions
Download patch file Download diff file Expand all files Collapse all files

20
mps/design/seg.txt
View file

@ -368,13 +368,19 @@ via the generic function ``SegReclaim()``.
_`.method.walk`: The ``walk`` method must call the visitor function
``f`` (along with its closure parameters ``v`` and ``s`` and the
format ``format``) once for each of the *black* objects in the
segment ``seg``. Padding objects may or may not be included in the
walk, at the segment's discretion: it is the responsibility of the
client program to handle them. Forwarding objects must not be included
in the walk. Segment classes need not provide this method. This
method is called by the genetic function ``SegWalk()``, which is
called by the heap walker ``mps_arena_formatted_objects_walk()``.
format ``format``) once for each of the *black* objects in the segment
``seg``. Padding objects may or may not be included in the walk, at
the segment's discretion: it is the responsibility of the client
program to handle them. Forwarding objects must not be included in the
walk. Segment classes need not provide this method. This method is
called by the generic function ``SegWalk()``, which is called by the
deprecated public functions ``mps_arena_formatted_objects_walk()`` and
``mps_amc_apply()``.
_`.method.walk.deprecated`: The ``walk`` method is deprecated along
with the public functions ``mps_arena_formatted_objects_walk()`` and
``mps_amc_apply()`` and will be removed along with them in a future
release.
``typedef void (*SegFlipMethod)(Seg seg, Trace trace)``

7
mps/manual/source/glossary/s.rst
View file

@ -703,10 +703,9 @@ Memory Management Glossary: S
A function that will be called on each element in a
collection. For example, a stepper function of type
:c:type:`mps_formatted_objects_stepper_t` can be passed to
:c:func:`mps_arena_formatted_objects_walk` and it will be
called on all :term:`formatted objects`
in an :term:`arena`.
:c:type:`mps_roots_stepper_t` can be passed to
:c:func:`mps_arena_roots_walk` and it will be called on
all :term:`roots` in an :term:`arena`.
sticky reference count

71
mps/manual/source/pool/amc.rst
View file

@ -139,74 +139,3 @@ AMC interface
MPS_ARGS_ADD(args, MPS_KEY_FORMAT, fmt);
res = mps_pool_create_k(&pool, arena, mps_class_amc(), args);
} MPS_ARGS_END(args);
.. index::
pair: AMC pool class; introspection
.. _pool-amc-introspection:
AMC introspection
-----------------
::
#include "mpscamc.h"
.. c:function:: void mps_amc_apply(mps_pool_t pool, mps_amc_apply_stepper_t f, void *p, size_t s)
Visit all :term:`formatted objects` in an AMC pool.
``pool`` is the pool whose formatted objects you want to visit.
``f`` is a function that will be called for each formatted object in
the pool.
``p`` and ``s`` are arguments that will be passed to ``f`` each time it
is called. This is intended to make it easy to pass, for example,
an array and its size as parameters.
It is an error to call this function when the :term:`arena` is not
in the :term:`parked state`. You need to call
:c:func:`mps_arena_collect` or :c:func:`mps_arena_park` before
calling :c:func:`mps_amc_apply`.
The function ``f`` will be called on both :term:`client <client
object>` and :term:`padding objects`. It is the job of ``f`` to
distinguish, if necessary, between the two. It may also be called
on :term:`dead` objects that the collector has not recycled or has
been unable to recycle.
.. note::
There is no equivalent function for other pool classes, but
there is a more general function
:c:func:`mps_arena_formatted_objects_walk` that visits all
formatted objects in the arena.
.. note::
This function is intended for heap analysis, tuning, and
debugging, not for frequent use in production.
.. c:type:: void (*mps_amc_apply_stepper_t)(mps_addr_t addr, void *p, size_t s)
The type of a :term:`stepper function` for :term:`formatted
objects` in an AMC pool.
``addr`` is the address of an object in the pool.
``p`` and ``s`` are the corresponding arguments that were passed
to :c:func:`mps_amc_apply`.
The function may not call any function in the MPS. It may access:
a. memory inside the object or block pointed to by ``addr``;
b. memory managed by the MPS that is in pools that do not protect
their contents;
c. memory not managed by the MPS;
It must not access other memory managed by the MPS.

5
mps/manual/source/release.rst
View file

@ -94,8 +94,9 @@ Interface changes
.. |unpack| replace:: :py:func:`struct.unpack`
.. _unpack: https://docs.python.org/3/library/struct.html#struct.unpack
#. The function :c:func:`mps_formatted_objects_walk` is deprecated in
favour of the new function :c:func:`mps_pool_walk`.
#. The functions :c:func:`mps_formatted_objects_walk` and
:c:func:`mps_amc_apply` are deprecated in favour of the new
function :c:func:`mps_pool_walk`.
Other changes

4
mps/manual/source/topic/arena.rst
View file

@ -951,8 +951,8 @@ Arena introspection and debugging
* :c:func:`mps_addr_fmt`: determine the :term:`object format` to
which an address belongs;
* :c:func:`mps_arena_formatted_objects_walk`: visit all
:term:`formatted objects` in an arena;
* :c:func:`mps_pool_walk`: visit all areas of :term:`formatted
objects` in a :term:`pool`;
* :c:func:`mps_arena_roots_walk`: visit all references in
:term:`roots` registered with an arena; and
* :c:func:`mps_addr_pool`: determine the :term:`pool` to which an

160
mps/manual/source/topic/deprecated.rst
View file

@ -63,6 +63,164 @@ Deprecated in version 1.118
limit is set to 1.0 exactly.
.. c:function:: void mps_arena_formatted_objects_walk(mps_arena_t arena, mps_formatted_objects_stepper_t f, void *p, size_t s)
.. deprecated::
Use :c:func:`mps_pool_walk` instead.
Visit all :term:`formatted objects` in an
:term:`arena`.
``arena`` is the arena whose formatted objects you want to visit.
``f`` is a formatted objects stepper function. It will be called for
each formatted object in the arena. See
:c:type:`mps_formatted_objects_stepper_t`.
``p`` and ``s`` are arguments that will be passed to ``f`` each time it
is called. This is intended to make it easy to pass, for example,
an array and its size as parameters.
Each :term:`pool class` determines for which objects the stepper
function is called. Typically, all validly formatted objects are
visited. :term:`Padding objects` may be visited at the pool
class's discretion: the stepper function must handle this
case.
.. warning::
The callback function must obey the restrictions documented
under :c:type:`mps_formatted_objects_stepper_t`.
If a garbage collection is currently in progress (that is, if
the arena is in the :term:`clamped <clamped state>` or
:term:`unclamped state`), then only objects that are known to
be currently valid are visited.
If you need to be certain that all objects are visited, or if
the callback function needs to follow references from the
object to automatically managed memory, you must ensure that
the arena is in the :term:`parked state` by calling
:c:func:`mps_arena_park` before calling this function (and
release it by calling :c:func:`mps_arena_release` afterwards,
if desired).
If your application has requirements for introspection that
can't be met under these restrictions, :ref:`contact us
<contact>`.
.. c:type:: void (*mps_formatted_objects_stepper_t)(mps_addr_t addr, mps_fmt_t fmt, mps_pool_t pool, void *p, size_t s)
.. deprecated::
Use :c:func:`mps_pool_walk` instead.
The type of a :term:`formatted objects`
:term:`stepper function`.
A function of this type can be passed to
:c:func:`mps_arena_formatted_objects_walk`, in which case it will
be called for each formatted object in an :term:`arena`. It
receives five arguments:
``addr`` is the address of the object.
``fmt`` is the :term:`object format` for that object.
``pool`` is the :term:`pool` to which the object belongs.
``p`` and ``s`` are the corresponding values that were passed to
:c:func:`mps_arena_formatted_objects_walk`.
The function may not call any function in the MPS. It may access:
a. memory inside the object or block pointed to by ``addr``;
b. memory managed by the MPS that is in pools that do not protect
their contents;
c. memory not managed by the MPS.
It must not:
d. access other memory managed by the MPS;
e. modify any of the references in the object.
.. c:function:: void mps_amc_apply(mps_pool_t pool, mps_amc_apply_stepper_t f, void *p, size_t s)
.. deprecated::
Use :c:func:`mps_pool_walk` instead.
Visit all :term:`formatted objects` in an AMC pool.
``pool`` is the pool whose formatted objects you want to visit.
``f`` is a function that will be called for each formatted object in
the pool.
``p`` and ``s`` are arguments that will be passed to ``f`` each time it
is called. This is intended to make it easy to pass, for example,
an array and its size as parameters.
It is an error to call this function when the :term:`arena` is not
in the :term:`parked state`. You need to call
:c:func:`mps_arena_collect` or :c:func:`mps_arena_park` before
calling :c:func:`mps_amc_apply`.
The function ``f`` will be called on both :term:`client <client
object>` and :term:`padding objects`. It is the job of ``f`` to
distinguish, if necessary, between the two. It may also be called
on :term:`dead` objects that the collector has not recycled or has
been unable to recycle.
.. note::
There is no equivalent function for other pool classes, but
there is a more general function
:c:func:`mps_arena_formatted_objects_walk` that visits all
formatted objects in the arena.
.. note::
This function is intended for heap analysis, tuning, and
debugging, not for frequent use in production.
.. c:type:: void (*mps_amc_apply_stepper_t)(mps_addr_t addr, void *p, size_t s)
.. deprecated::
Use :c:func:`mps_pool_walk` instead.
The type of a :term:`stepper function` for :term:`formatted
objects` in an AMC pool.
``addr`` is the address of an object in the pool.
``p`` and ``s`` are the corresponding arguments that were passed
to :c:func:`mps_amc_apply`.
The function may not call any function in the MPS. It may access:
a. memory inside the object or block pointed to by ``addr``;
b. memory managed by the MPS that is in pools that do not protect
their contents;
c. memory not managed by the MPS;
It must not:
d. access other memory managed by the MPS;
e. modify any of the references in the object.
.. index::
single: deprecated interfaces; in version 1.115
@ -77,7 +235,7 @@ Deprecated in version 1.115
pools were the only objects in the MPS that belonged to
classes.
.. c:function:: size_t mps_mvff_free_size(mps_pool_t pool)
.. deprecated::

3
mps/manual/source/topic/error.rst
View file

@ -321,8 +321,7 @@ this documentation.
The client program has made a re-entrant call into the MPS. Look
at the backtrace to see what it was. Common culprits are signal
handlers, assertion handlers, :term:`format methods`, and
:term:`stepper functions`.
handlers, assertion handlers, and :term:`format methods`.
``locus.c: gen->activeTraces == TraceSetEMPTY``

79
mps/manual/source/topic/format.rst
View file

@ -487,82 +487,3 @@ Object format introspection
managed by a pool with an object format, but which is not
inside a block allocated by that pool. It never returns a
false negative.
.. c:function:: void mps_arena_formatted_objects_walk(mps_arena_t arena, mps_formatted_objects_stepper_t f, void *p, size_t s)
Visit all :term:`formatted objects` in an
:term:`arena`.
``arena`` is the arena whose formatted objects you want to visit.
``f`` is a formatted objects stepper function. It will be called for
each formatted object in the arena. See
:c:type:`mps_formatted_objects_stepper_t`.
``p`` and ``s`` are arguments that will be passed to ``f`` each time it
is called. This is intended to make it easy to pass, for example,
an array and its size as parameters.
Each :term:`pool class` determines for which objects the stepper
function is called. Typically, all validly formatted objects are
visited. :term:`Padding objects` may be visited at the pool
class's discretion: the stepper function must handle this
case.
.. warning::
The callback function must obey the restrictions documented
under :c:type:`mps_formatted_objects_stepper_t`.
If a garbage collection is currently in progress (that is, if
the arena is in the :term:`clamped <clamped state>` or
:term:`unclamped state`), then only objects that are known to
be currently valid are visited.
If you need to be certain that all objects are visited, or if
the callback function needs to follow references from the
object to automatically managed memory, you must ensure that
the arena is in the :term:`parked state` by calling
:c:func:`mps_arena_park` before calling this function (and
release it by calling :c:func:`mps_arena_release` afterwards,
if desired).
If your application has requirements for introspection that
can't be met under these restrictions, :ref:`contact us
<contact>`.
.. c:type:: void (*mps_formatted_objects_stepper_t)(mps_addr_t addr, mps_fmt_t fmt, mps_pool_t pool, void *p, size_t s)
The type of a :term:`formatted objects`
:term:`stepper function`.
A function of this type can be passed to
:c:func:`mps_arena_formatted_objects_walk`, in which case it will
be called for each formatted object in an :term:`arena`. It
receives five arguments:
``addr`` is the address of the object.
``fmt`` is the :term:`object format` for that object.
``pool`` is the :term:`pool` to which the object belongs.
``p`` and ``s`` are the corresponding values that were passed to
:c:func:`mps_arena_formatted_objects_walk`.
The function may not call any function in the MPS. It may access:
a. memory inside the object or block pointed to by ``addr``;
b. memory managed by the MPS that is in pools that do not protect
their contents;
c. memory not managed by the MPS.
It must not:
d. access other memory managed by the MPS;
e. modify any of the references in the object.