1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
.. sources:

    `<https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/protocol/mps/root/>`_

.. index::
   single: root; introduction

.. _topic-root:

Roots
=====

:term:`Roots` tell the :term:`garbage collector` where to start
:term:`tracing <trace>`. The garbage collector determines which blocks
are :term:`reachable` from the roots, and (in :term:`automatically
managed <automatic memory management>` :term:`pools`) reclaims
the :term:`unreachable` blocks. This is quite efficient and can be a
very good approximation to :term:`liveness <live>`.

It is therefore important that all :term:`references` that the
:term:`client program` can directly access are registered as roots,
otherwise the garbage collector might recycle an object that would be
used in the future. Some collectors, for example Boehm's, assume that
all references stored in static data are roots; the Memory Pool System
is more flexible, but requires the client program to declare which
references are roots.


.. index::
   single: root; registering

Registering roots
-----------------

You can register a root at any time by calling one of the
``mps_root_create`` functions. Roots may not be registered twice, and
no two roots may overlap (that is, each reference is :term:`fixed` by
at most one root). Roots may be:

#. in :term:`registers`;

#. on the program's :term:`control stack`;

#. in the program's static data;

#. in :term:`heap` not managed by the MPS (provided that you destroy
   the root before freeing it; see :ref:`the Scheme interpreter's
   global symbol table <guide-lang-roots-rehash>` for an example);

#. in :term:`manually managed <manual memory management>` pools
   (provided that you remove the root before freeing it).

Roots must not be in memory that is subject to :term:`garbage
collection` (and so roots must not be in :term:`automatically managed
<automatic memory management>` pools).

When you register a root you describe to the MPS how to :term:`scan`
it for references, providing your own scanning function in the cases
of :c:func:`mps_root_create` and :c:func:`mps_root_create_fmt`. Such a
root scanning function must follow the :ref:`topic-scanning-protocol`.

All the references in a root are of the same :term:`rank` (just as in
a :term:`formatted object`). So they are all :term:`exact <exact
reference>`, :term:`ambiguous <ambiguous reference>` or :term:`weak
<weak reference (1)>`.

.. note::

    If the rank of the root is :term:`exact <exact reference>`, or
    :term:`weak <weak reference (1)>`, the references in the root must
    always be valid while the root is registered: that is, they must
    be references to actual objects or null pointers. This could be
    immediately after the root is registered, so the root must be
    valid before it is registered.

.. note::

    As with :ref:`scanning <topic-scanning>` in general, it's safe to
    :term:`fix` references that point to memory not managed by the
    MPS. These will be ignored.

Roots can be deregistered at any time by calling
:c:func:`mps_root_destroy`. All roots registered in an :term:`arena`
must be deregistered before the arena is destroyed.

There are four ways to register a root, depending on how you need to
scan it for references:

#. :c:func:`mps_root_create` if you need a custom root scanning
   function (of type :c:type:`mps_root_scan_t`);

#. :c:func:`mps_root_create_fmt` if the root consists of a block of
   objects belonging to an :term:`object format`, which can be scanned
   by the format's :term:`scan method` (of type
   :c:type:`mps_fmt_scan_t`);

#. :c:func:`mps_root_create_area` if the root consists of an area
   of memory;

#. :c:func:`mps_root_create_thread` if the root consists of the
   :term:`registers` and :term:`control stack` of a thread. See
   :ref:`topic-root-thread` below.

Several of these categories of roots have variants for dealing with
:term:`tagged references`.  See :ref:`topic-scanning-tag`.

.. index::
   pair: root; cautions

Cautions
--------

Creating a root and then registering is similar to reserving a block
and then committing it (in the
:ref:`topic-allocation-point-protocol`), and similar :ref:`cautions
<topic-allocation-cautions>` apply. Before registering a root:

#. The root must be valid (that is, the appropriate root scanning
   function can scan it).

#. All :term:`exact references` in the root (references that are
   :term:`fixed` by the root scanning function) must contain valid
   references or null pointers.

#. You must not store a reference in the root to a block in an
   automatically managed pool (such a reference is hidden from the MPS
   until you register the root, and may become invalid).

So the typical sequence of operations when creating a root is:

#. Initialize references in the root with null pointers or other safe
   values.

#. Register the root.

#. Fill in the references in the root.


.. index::
   pair: root; thread

.. _topic-root-thread:

Thread roots
------------

Every thread's :term:`registers` and :term:`control stack` potentially
contain references to allocated objects, so should be registered as a
root by calling :c:func:`mps_root_create_thread`.

The MPS's stack scanner needs to know how to find the :term:`cold end`
of the part of the stack to scan. The :term:`cold end` of the relevant
part of the stack can be found by taking the address of a local
variable in the function that calls the main work function of your
thread. You should take care to ensure that the work function is not
inlined so that the address is definitely in the stack frame below any
potential roots.

.. index::
   single: Scheme; thread root

For example, here's the code from the toy Scheme interpreter that
registers a thread root and then calls the program::

    mps_thr_t thread;
    mps_root_t stack_root;
    int exit_code;
    void *cold = &cold;

    res = mps_thread_reg(&thread, arena);
    if (res != MPS_RES_OK) error("Couldn't register thread");

    res = mps_root_create_thread(&stack_root, arena, thread, cold);
    if (res != MPS_RES_OK) error("Couldn't create root");

    exit_code = start(argc, argv);

    mps_root_destroy(stack_root);
    mps_thread_dereg(thread);


.. index::
   pair: root; rank

Ranks
-----

.. c:type:: mps_rank_t

    The type of :term:`ranks`. It is a :term:`transparent alias
    <transparent type>` for ``unsigned int``, provided for convenience
    and clarity.


.. c:function:: mps_rank_t mps_rank_ambig(void)

    Return the :term:`rank` of :term:`ambiguous roots`.


.. c:function:: mps_rank_t mps_rank_exact(void)

    Return the :term:`rank` of :term:`exact roots`.


.. c:function:: mps_rank_t mps_rank_weak(void)

    Return the :term:`rank` of :term:`weak roots`.


.. index::
   pair: root; mode

Root modes
----------

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 *constant* need not be re-scanned, and roots that are
declared to be *protectable* may have barriers placed on them,
allowing the MPS to detect whether they have changed.

.. note::

    The MPS does not currently perform either of these optimizations,
    so root modes have no effect. These features may be added in a
    future release.


.. c:type:: mps_rm_t

    The type of :term:`root modes`.

    It should be zero (meaning neither constant or protectable), or
    the sum of some of :c:macro:`MPS_RM_CONST`,
    :c:macro:`MPS_RM_PROT`, and :c:macro:`MPS_RM_PROT_INNER`.


.. c:macro:: MPS_RM_CONST

    .. deprecated:: starting with version 1.111.

        This was introduced in the hope of being able to maintain a
        :term:`remembered set` for the root without needing a
        :term:`write barrier`, but it can't work as described, since
        you can't reliably create a valid registered constant root that
        contains any references. (If you add the references before
        registering the root, they may have become invalid; but you
        can't add them afterwards because the root is supposed to be
        constant.)

    The :term:`root mode` for :term:`constant roots`.
    This tells the MPS that the :term:`client program` will not change
    the :term:`root` after it is registered: that is, scanning the
    root will produce the same set of :term:`references`
    every time. Furthermore, for roots registered by
    :c:func:`mps_root_create_fmt` and :c:func:`mps_root_create_area`,
    the client program will not write to the root at all.

.. c:macro:: MPS_RM_PROT

    The :term:`root mode` for :term:`protectable roots`. This tells
    the MPS that it may place a :term:`barrier (1)` on any
    :term:`page` containing any part of the :term:`root`. No
    :term:`format method` or :term:`scan method` (except for the one
    for this root) may write data in this root. They may read it.

    .. note::

        You must not specify ``MPS_RM_PROT`` on a root allocated by
        the MPS.

        No page may contain parts of two or more protectable roots.
        You mustn't specify ``MPS_RM_PROT`` if the :term:`client
        program` or anything other than (this instance of) the MPS is
        going to protect or unprotect the relevant pages.

        This mode may not be suitable if the :term:`client program`
        wants the operating system to be able to access the root. Many
        operating systems can't cope with writing to protected pages.

.. c:macro:: MPS_RM_PROT_INNER

    The :term:`root mode` for :term:`protectable roots` whose inner
    pages (only) may be protected. This mode must not be specified
    unless :c:macro:`MPS_RM_PROT` is also specified. It tells the MPS
    that it may not place a :term:`barrier (1)` on a :term:`page`
    that's partly (but not wholly) covered by the :term:`root`.


.. index::
   single: root; interface

Root interface
--------------

.. c:type:: mps_root_t

    The type of :term:`root` descriptions.

    The :term:`arena` uses root descriptions to find
    :term:`references` within the :term:`client program's <client
    program>` roots.


.. c:function:: mps_res_t mps_root_create(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_root_scan_t root_scan, void *p, size_t s)

    Register a :term:`root` that consists of the :term:`references` fixed by a scanning function.

    ``root_o`` points to a location that will hold the address of the
    new root description.

    ``arena`` is the arena.

    ``rank`` is the :term:`rank` of references in the root.

    ``rm`` is the :term:`root mode`.

    ``root_scan`` is the root scanning function. See
    :c:type:`mps_root_scan_t`.

    ``p`` and ``s`` are arguments that will be passed to ``root_scan`` each
    time it is called. This is intended to make it easy to pass, for
    example, an array and its size as parameters.

    Returns :c:macro:`MPS_RES_OK` if the root was registered
    successfully, :c:macro:`MPS_RES_MEMORY` if the new root
    description could not be allocated, or another :term:`result code`
    if there was another error.

    The registered root description persists until it is destroyed by
    calling :c:func:`mps_root_destroy`.

    This is the most general kind of root, but gives the MPS the least
    information to use for optimisation.  Use a more specialized kind
    of root whenever possible.


.. c:type:: mps_res_t (*mps_root_scan_t)(mps_ss_t ss, void *p, size_t s)

    The type of root scanning functions for :c:func:`mps_root_create`.

    ``ss`` is the :term:`scan state`. It must be passed to
    :c:macro:`MPS_SCAN_BEGIN` and :c:macro:`MPS_SCAN_END` to delimit a
    sequence of fix operations, and to the functions
    :c:func:`MPS_FIX1` and :c:func:`MPS_FIX2` when fixing a
    :term:`reference`.

    ``p`` and ``s`` are the corresponding values that were passed to
    :c:func:`mps_root_create`.

    Returns a :term:`result code`. If a fix function returns a value
    other than :c:macro:`MPS_RES_OK`, the scan method must return that
    value, and may return without fixing any further references.
    Generally, it is better if it returns as soon as possible. If the
    scanning is completed successfully, the function should return
    :c:macro:`MPS_RES_OK`.


.. c:function:: mps_res_t mps_root_create_fmt(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_fmt_scan_t fmt_scan, mps_addr_t base, mps_addr_t limit)

    Register a :term:`root` that consists of the :term:`references` fixed by a scanning function in a block of
    :term:`formatted objects`.

    ``root_o`` points to a location that will hold the address of the
    new root description.

    ``arena`` is the arena.

    ``rank`` is the :term:`rank` of references in the root.

    ``rm`` is the :term:`root mode`.

    ``fmt_scan`` is a scanning function. See :c:type:`mps_fmt_scan_t`.

    ``base`` is the address of the base of the block of formatted
    objects.

    ``limit`` is the address just beyond the end of the block of
    formatted objects.

    Returns :c:macro:`MPS_RES_OK` if the root was registered
    successfully, :c:macro:`MPS_RES_MEMORY` if the new root
    description could not be allocated, or another :term:`result code`
    if there was another error.

    The registered root description persists until it is destroyed by
    calling :c:func:`mps_root_destroy`.


.. c:function:: mps_res_t mps_root_create_thread(mps_root_t *root_o, mps_arena_t arena, mps_thr_t thr, void *cold)

    Register a :term:`root` that consists of the :term:`references` in
    a :term:`thread's <thread>` registers and stack that are word aligned.
    This is the most common kind of thread root.

    This function is equivalent to calling::

        mps_root_create_thread_tagged(root_o,
                                      arena,
                                      mps_rank_ambig(),
                                      (mps_rm_t)0,
                                      thr,
                                      mps_scan_area_tagged,
                                      sizeof(mps_word_t) - 1,
                                      0,
                                      cold);

.. c:function:: mps_res_t mps_root_create_thread_tagged(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thr, mps_area_scan_t scan_area, mps_word_t mask, mps_word_t pattern, void *cold)

    Register a :term:`root` that consists of the :term:`references` in
    a :term:`thread's <thread>` registers and stack that match a
    binary pattern, for instance tagged as pointers.

    ``root_o`` points to a location that will hold the address of the
    new root description.

    ``arena`` is the arena.

    ``rank`` is the :term:`rank` of references in the root.

    ``rm`` is the :term:`root mode`.

    ``thr`` is the thread.

    ``scan_area`` is an tagged area scanning function that will be used
    to scan the threads registers and stack, for example
    :c:func:`mps_scan_area_tagged` or
    :c:func:`mps_scan_area_tagged_or_zero`.  See
    :ref:`topic-scanning-area`.

    ``mask`` is a :term:`bitmask` that is passed to ``scan_area`` to
    be applied to the thread's registers and stack to locate the
    :term:`tag`.

    ``pattern`` is passed to ``scan_area`` to determine whether to
    consider a word as a reference.  For example,
    :c:func:`mps_scan_area_tagged` will not consider any word that is
    unequal to this (after masking with ``mask``) to be a reference.

    ``cold`` is a pointer to the :term:`cold end` of stack to be
    scanned. On platforms where the stack grows downwards (currently,
    all supported platforms), locations below this address will be
    scanned.

    Returns :c:macro:`MPS_RES_OK` if the root was registered
    successfully, :c:macro:`MPS_RES_MEMORY` if the new root
    description could not be allocated, or another :term:`result code`
    if there was another error.

    The registered root description persists until it is destroyed by
    calling :c:func:`mps_root_destroy`.

    .. warning::

        A risk of using tagged pointers in registers and on the stack
        is that in some circumstances, an optimizing compiler might
        optimize away the tagged pointer, keeping only the untagged
        version of the pointer. In this situation the pointer would be
        ignored and if it was the last reference to the object the MPS
        might incorrectly determine that it was dead. 

        You can avoid this risk in several ways:

        #. Choose to tag pointers with zero, setting ``scan_area`` to
           :c:func:`mps_scan_area_tagged` and setting ``pattern`` to
           zero.

        #. Set ``scan_area`` to :c:func:`mps_scan_area_tagged_or_zero`
           so that untagged pointers are scanned.  This may lead to
           some additional scanning and retention.

        #. Use :c:func:`mps_root_create_thread_scanned` and set
           ``scan_area`` to :c:func:`mps_scan_area`: in this case all
           words in registers and on the stack are scanned, leading to
           possible additional scanning and retention.

        #. Write your own compiler with complete control over register
           contents and stack format, use
           :c:func:`mps_root_create_thread_scanned` and set
           ``scan_area`` to your own custom scanner, derived from the
           source code of :c:func:`mps_scan_area`, that knows the
           format.

     .. note::

        An optimization that may be worth considering is setting some
        of the top bits in ``mask`` and ``pattern`` so that addresses
        that cannot be allocated by the MPS are rejected quickly. This
        requires expertise with the platform's virtual memory
        interface.

.. c:function:: mps_res_t mps_root_create_thread_scanned(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thread, mps_area_scan_t scan_area, void *closure, void *cold)

    Register a :term:`root` that consists of the :term:`references` in
    a :term:`thread's <thread>` registers and stack, scanned by an
    arbitrary area scanning function.

    ``root_o`` points to a location that will hold the address of the
    new root description.

    ``arena`` is the arena.

    ``rank`` is the :term:`rank` of references in the root.

    ``rm`` is the :term:`root mode`.

    ``thr`` is the thread.

    ``scan_area`` is an area scanning function that will be used to
    scan the threads registers and stack, for example
    :c:func:`mps_scan_area`, or a similar user-defined function. See
    :ref:`topic-scanning-area`.

    ``closure`` is an arbitrary pointer that will be passed to
    ``scan_area`` and is intended to point to any parameters it needs.
    Ensure anything it points to exists as long as the root exists.

    ``cold`` is a pointer to the :term:`cold end` of stack to be
    scanned. On platforms where the stack grows downwards (currently,
    all supported platforms), locations below this address will be
    scanned.

    Returns :c:macro:`MPS_RES_OK` if the root was registered
    successfully, :c:macro:`MPS_RES_MEMORY` if the new root
    description could not be allocated, or another :term:`result code`
    if there was another error.

    The registered root description persists until it is destroyed by
    calling :c:func:`mps_root_destroy`.

.. c:function:: mps_res_t mps_root_create_area(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, void *base, void *limit, mps_area_scan_t scan_area, void *closure)

    Register a :term:`root` that consists of an area of memory scanned
    by an area scanning function.

    ``root_o`` points to a location that will hold the address of the
    new root description.

    ``arena`` is the arena.

    ``rank`` is the :term:`rank` of references in the root.

    ``rm`` is the :term:`root mode`.

    ``base`` points to the first word to be scanned.

    ``limit`` points to the location just beyond the end of the area
    to be scanned.

    ``scan_area`` is an area scanning function, for example
    :c:func:`mps_scan_area`, or a similar user-defined function. See
    :ref:`topic-scanning-area`.

    ``closure`` is an arbitrary pointer that will be passed to
    ``scan_area`` and intended to point to any parameters it needs.
    Ensure anything it points to exists as long as the root exists.

    Returns :c:macro:`MPS_RES_OK` if the root was registered
    successfully, :c:macro:`MPS_RES_MEMORY` if the new root
    description could not be allocated, or another :term:`result code`
    if there was another error.

    The registered root description persists until it is destroyed by
    calling :c:func:`mps_root_destroy`.

.. c:function:: mps_res_t mps_root_create_area_tagged(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, void *base, void *limit, mps_area_scan_t scan_area, mps_word_t mask, mps_word_t pattern)

    Register a :term:`root` that consists of an area of memory scanned by
    a tagged area scanning function.

    ``root_o`` points to a location that will hold the address of the
    new root description.

    ``arena`` is the arena.

    ``rank`` is the :term:`rank` of references in the root.

    ``rm`` is the :term:`root mode`.

    ``base`` points to a vector of tagged references.

    ``limit`` points to the location just beyond the end of the vector
    of tagged references.

    ``scan_area`` is an tagged area scanning function that will be
    used to scan the area, for example :c:func:`mps_scan_area_tagged`
    or :c:func:`mps_scan_area_tagged_or_zero`.  The ``closure``
    argument to ``scan_area`` is a :c:type:`mps_scan_tag_t` cast to
    ``void *`` See :ref:`topic-scanning-area`.

    ``mask`` is a :term:`bitmask` that is passed to ``scan_area`` to
    be applied to the words in the vector to locate the :term:`tag`.

    ``pattern`` is passed to ``scan_area`` to determine whether to
    consider a word as a reference.  For example,
    :c:func:`mps_scan_area_tagged` will not consider any word that is
    unequal to this (after masking with ``mask``) to be a reference.

    Returns :c:macro:`MPS_RES_OK` if the root was registered
    successfully, :c:macro:`MPS_RES_MEMORY` if the new root
    description could not be allocated, or another :term:`result code`
    if there was another error.

    The registered root description persists until it is destroyed by
    calling :c:func:`mps_root_destroy`.

    For example::

        #define TAG_MASK 0x3            /* bottom two bits */
        #define TAG_PATTERN 0x1         /* bottom bit set for references */

        /* Global symbol table. */
        size_t symtab_size;
        struct {
            obj_t symbol;
            obj_t value;
        } *symtab;

        mps_res_t res;
        mps_root_t root;
        res = mps_root_create_area_tagged(&root, arena,
                                          mps_rank_exact(),
                                          0,
                                          symtab, symtab + symtab_size,
                                          mps_scan_area_tagged,
                                          TAG_MASK, TAG_PATTERN);
        if (res != MPS_RES_OK) error("can't create symtab root");

.. c:function:: void mps_root_destroy(mps_root_t root)

    Deregister a :term:`root` and destroy its description.

    ``root`` is the root.


.. index::
   pair: root; introspection

Root introspection
------------------

.. c:function:: void mps_arena_roots_walk(mps_arena_t arena, mps_roots_stepper_t f, void *p, size_t s)

    .. deprecated:: starting with version 1.111.

        If you think you need this, there's probably a better way to
        achieve what you're trying to do. :ref:`Contact us <contact>`.

    Visit references in registered :term:`roots` in an
    :term:`arena`.

    ``arena`` is the arena whose roots you want to visit.

    ``f`` is a function that will be called for each reference to an
    object in an :term:`automatically <automatic memory management>`
    managed :term:`pool class` that was found in a registered root
    belonging to the arena. It takes four arguments: ``ref`` is the
    address of a reference to an object in the arena, ``root`` is the
    root in which ``ref`` was found, and ``p`` and ``s`` are the
    corresponding arguments that were passed to
    :c:func:`mps_arena_roots_walk`.

    ``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.

    This function may only be called when the arena is in the
    :term:`parked state`.

    .. seealso::

        :ref:`topic-arena`.

    .. note::

        If a root is :term:`ambiguous <ambiguous root>` then the
        reference might not be to the start of an object; the
        :term:`client program` should handle this case. There is no
        guarantee that the reference corresponds to the actual
        location that holds the pointer to the object (since this
        might be a register, for example), but the actual location
        will be passed if possible. This may aid analysis of roots via
        a debugger.


.. c:type:: void (*mps_roots_stepper_t)(mps_addr_t *ref, mps_root_t root, void *p, size_t s)

    The type of a :term:`root` :term:`stepper function`.

    A function of this type can be passed to
    :c:func:`mps_arena_roots_walk`, in which case it will be called
    for each reference into the :term:`arena` from a root registered
    with the arena. It receives four arguments:

    ``ref`` points to a reference in a root. The reference points to
    something in the arena. If the root is :term:`exact <exact
    reference>` then the reference points to the start of an allocated
    block, but if the root is :term:`ambiguous <ambiguous reference>`
    it might point to somewhere in the middle of an allocated block.

    ``root`` is the description of the root which contains ``ref``.

    ``p`` and ``s`` are the corresponding values that were passed to
    :c:func:`mps_arena_roots_walk`.