From 84389cd5401b34ba1ddc69397a0c0bce83ecbc4e Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Sun, 23 Aug 2020 14:39:21 +0100 Subject: [PATCH] Improve documentation of mps_arena_formatted_objects_walk(). Make it clearer that the callback must not modify references, or follow references to automatically managed memory, unless the arena is parked. Add invitation to contact us if the function does not meet the application requirements due to these restrictions. --- mps/manual/source/topic/format.rst | 31 +++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst index 83087db816c..1ee992fbd4e 100644 --- a/mps/manual/source/topic/format.rst +++ b/mps/manual/source/topic/format.rst @@ -510,22 +510,27 @@ Object format introspection class's discretion: the stepper function must handle this case. - .. note:: - - This function is intended for heap analysis, tuning, and - debugging, not for frequent use in production. - .. 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. - For the most reliable results, ensure 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 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) @@ -554,6 +559,10 @@ Object format introspection b. memory managed by the MPS that is in pools that do not protect their contents; - c. memory not managed by the MPS; + c. memory not managed by the MPS. - It must not access other memory managed by the MPS. + It must not: + + d. access other memory managed by the MPS; + + e. modify any of the references in the object.