Write debugging pools chapter.

Copied from Perforce
 Change: 180099
 ServerID: perforce.ravenbrook.com

mps/manual/source/guide/debug.rst

@@ -45,12 +45,13 @@ General debugging advice
 
     .. _address space layout randomization: http://en.wikipedia.org/wiki/Address_space_layout_randomization
 
-   A fact that assists with reproducibility is that the more frequently
-   the collector runs, the sooner and more reliably errors are
-   discovered. So if you have a bug that's hard to reproduce, you may
-   be able to provoke it more reliably by having a mode for testing in
-   which you run frequent collections (by calling
-   :c:func:`mps_arena_collect` followed by
+   A fact that assists with reproducibility is that the more
+   frequently the collector runs, the sooner and more reliably errors
+   are discovered. So if you have a bug that's hard to reproduce, or
+   which manifests itself in different ways on different runs, you may
+   be able to provoke it more reliably, or get a more consistent
+   result by having a mode for testing in which you run frequent
+   collections (by calling :c:func:`mps_arena_collect` followed by
    :c:func:`mps_arena_release`), perhaps as frequently as every
    allocation.
 

mps/manual/source/guide/perf.rst

@@ -3,4 +3,4 @@
 Tuning the Memory Pool System for performance
 =============================================
 
-See <https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mminfo/strategy/lisp-machine/>
+Choice of pools.

mps/manual/source/pool/pool-ams.rst

@@ -28,14 +28,14 @@ AMS symbol reference
 
 .. c:function:: mps_class_t mps_class_ams(void)
 
-    Return the :term:`pool class` for an AMC (Automatic
-    Mostly-Copying) :term:`pool`.
+    Return the :term:`pool class` for an AMS (Automatic Mark & Sweep)
+    :term:`pool`.
 
-    When creating an AMC pool, :c:func:`mps_pool_create` takes two
+    When creating an AMS pool, :c:func:`mps_pool_create` takes two
     extra arguments::
 
         mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, 
-                                  mps_class_t mps_class_amc(),
+                                  mps_class_t mps_class_ams(),
                                   mps_fmt_t fmt,
                                   mps_chain_t chain)
 

mps/manual/source/topic/collection.rst

@@ -111,6 +111,12 @@ generation`. When the nursery's "new size" exceeds its capacity, the
 MPS considers collecting the pool. (Whether it actually does so or not
 depends on which other collections on other pools are in progress.)
 
+.. note::
+
+    You can affect the decision as to when to collect the nursery
+    generation by using the :ref:`ramp allocation pattern
+    <topic-pattern-ramp>`.
+
 If the MPS decides to collect a pool at all, all generations are
 collected below the first generation whose "new size" is less than its
 capacity.

mps/manual/source/topic/debugging.rst

@@ -7,47 +7,47 @@
 Debugging pools
 ===============
 
-::
+Several :term:`pool classes <pool class>` have debugging counterparts
+that provide two features that are useful for debugging:
 
-    static mps_pool_debug_option_s debugOptions = {
+* :dfn:`fenceposts` are patterns of data that are written before and
+  after each allocated block. These patterns can be checked, for
+  example when the block is deallocated, to see that they are
+  unchanged. This helps detect underwriting and :term:`overwriting
+  errors <overwriting error>`.
+
+* :dfn:`free space splatting` overwrites recycled space with a pattern
+  of data. If the pattern is designed so that it does not resemble a
+  live object (and if code checks the consistency of its data
+  structues), then this helps to detect :term:`dangling pointer`
+  dereferences. The pattern can also be checked, for example just
+  before allocation, or when a block of memory is released from the
+  pool to the arena, to see that it is unchanged.
+
+The :term:`client program` specifies templates for both of these
+features via the :c:type:`mps_pool_debug_option_s` structure. This
+allows it to specify patterns:
+
+* that mimic illegal data values;
+
+* that cause bus errors if wrongly interpreted as pointers;
+
+* that cause assertions to fire if wrongly interpreted as data values;
+
+* that contain an instruction sequence that wold cause the program to
+  signal an error or stop if wrongly interpreted as executable code.
+
+For example::
+
+    mps_pool_debug_option_s debug_options = {
        (void *)"postpost", 8,
        (void *)"freefree", 8,
     };
-    if (mps_pool_create(&pool, arena, mps_class_ams_debug(),
-                        &debugOptions, 8192, 135, 8)
-        != MPS_RES_OK)
-    {
-        printf("Error creating pool!");
-        exit(2);
-    }
-
-
-Interface
----------
-
-.. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool)
-
-    Check all the :term:`fenceposts <fencepost>` in a :term:`pool`.
-
-    ``pool`` is the pool whose fenceposts are to be checked.
-
-    If a corrupted fencepost is found, the MPS will :term:`assert
-    <assertion>`. It is only useful to call this on a :term:`debugging
-    pool` that has fenceposts turned on. It does nothing on
-    non-debugging pools.
-
-
-.. c:function:: void mps_pool_check_free_space(mps_pool_t mps_pool)
-
-    Check all the free space in a :term:`pool` for :term:`overwriting
-    errors <overwriting error>`
-
-    ``pool`` is the pool whose free space is to be checked.
-
-    If corrupted free space is found, the MPS will :term:`assert
-    <assertion>`. It is only useful to call this on a :term:`debugging
-    pool` that has free space splatting turned on. It does nothing on
-    non-debugging pools.
+    mps_pool_t pool;
+    mps_res_t res;
+    res = mps_pool_create(&pool, arena, mps_class_ams_debug(),
+                          &debug_options, &fmt, &chain)
+    if (res != MPS_RES_OK) error("can't create debug pool");
 
 
 .. c:type:: mps_pool_debug_option_s
@@ -89,17 +89,27 @@ Interface
     pieces smaller than the given size, for example to pad out part of
     a block that was left unused because of alignment requirements.
 
-    Fencepost and free space templates allow the :term:`client
-    program` to specify patterns:
 
-    * that mimic illegal data values;
-  
-    * that cause bus errors if wrongly interpreted as pointers;
+.. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool)
 
-    * that cause assertions to fire if wrongly interpreted as data values;
+    Check all the :term:`fenceposts <fencepost>` in a :term:`pool`.
 
-    * that contain an instruction sequence that wold cause the program
-      to signal an error or stop if wrongly interpreted as executable
-      code.
+    ``pool`` is the pool whose fenceposts are to be checked.
+
+    If a corrupted fencepost is found, the MPS will :term:`assert
+    <assertion>`. It is only useful to call this on a :term:`debugging
+    pool` that has fenceposts turned on. It does nothing on
+    non-debugging pools.
 
 
+.. c:function:: void mps_pool_check_free_space(mps_pool_t mps_pool)
+
+    Check all the free space in a :term:`pool` for :term:`overwriting
+    errors <overwriting error>`
+
+    ``pool`` is the pool whose free space is to be checked.
+
+    If corrupted free space is found, the MPS will :term:`assert
+    <assertion>`. It is only useful to call this on a :term:`debugging
+    pool` that has free space splatting turned on. It does nothing on
+    non-debugging pools.

mps/manual/source/topic/pattern.rst

@@ -7,7 +7,7 @@
 Allocation patterns
 ===================
 
-An :dfb:`allocation pattern` is a hint to the MPS to expect a
+An :dfn:`allocation pattern` is a hint to the MPS to expect a
 particular pattern of allocation on an :term:`allocation point`. The
 MPS may use this hint to schedule its decisions as to when and what to
 collect.
@@ -85,6 +85,8 @@ collect.
     This function may be used to recover from error conditions.
 
 
+.. _topic-pattern-ramp:
+
 Ramp allocation
 ---------------