diff --git a/mps/design/seg.txt b/mps/design/seg.txt index 1b192ed2907..809c76682a9 100644 --- a/mps/design/seg.txt +++ b/mps/design/seg.txt @@ -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)`` diff --git a/mps/manual/source/glossary/s.rst b/mps/manual/source/glossary/s.rst index 234537c0d94..2b633edc97e 100644 --- a/mps/manual/source/glossary/s.rst +++ b/mps/manual/source/glossary/s.rst @@ -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 diff --git a/mps/manual/source/pool/amc.rst b/mps/manual/source/pool/amc.rst index f768a3a389a..4760f928bd1 100644 --- a/mps/manual/source/pool/amc.rst +++ b/mps/manual/source/pool/amc.rst @@ -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 ` 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. diff --git a/mps/manual/source/release.rst b/mps/manual/source/release.rst index e45f568671d..6ff3db29589 100644 --- a/mps/manual/source/release.rst +++ b/mps/manual/source/release.rst @@ -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 diff --git a/mps/manual/source/topic/arena.rst b/mps/manual/source/topic/arena.rst index 864e592306a..0e6e086e9bf 100644 --- a/mps/manual/source/topic/arena.rst +++ b/mps/manual/source/topic/arena.rst @@ -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 diff --git a/mps/manual/source/topic/deprecated.rst b/mps/manual/source/topic/deprecated.rst index 4dd90a1e1d6..b61e1a71653 100644 --- a/mps/manual/source/topic/deprecated.rst +++ b/mps/manual/source/topic/deprecated.rst @@ -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 ` 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 + `. + + +.. 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 ` 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:: diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst index 832d9a77b93..7fbef9abb5e 100644 --- a/mps/manual/source/topic/error.rst +++ b/mps/manual/source/topic/error.rst @@ -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`` diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst index 91f1e0035e3..7ec2a9916c9 100644 --- a/mps/manual/source/topic/format.rst +++ b/mps/manual/source/topic/format.rst @@ -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 ` 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 - `. - - -.. 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.