Update manual to describe new condemn logic resulting from fix for job003771.

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

mps/manual/source/release.rst

@@ -26,6 +26,20 @@ New features
    :c:macro:`MPS_KEY_INTERIOR` keyword argument to ``FALSE`` when
    calling :c:func:`mps_pool_create_k`.
 
+#. The logic for deciding which generations should be collected has
+   changed. Now, a chain may be scheduled for collection if the new
+   size of *any* of its generations exceeds its capacity, and when a
+   chain is collected, all generations are collected up to, and
+   including, the highest generation whose new size exceeds its
+   capacity. This ensures that all generations are collected reliably
+   on chains where there is no allocation into the nursery generation.
+   See :ref:`topic-collection-schedule`.
+
+   (Previously, only the nursery generation in each chain
+   was considered, and a chain was collected up to, but not including,
+   the lowest generation whose new size was within its capacity.)
+
+
 
 Interface changes
 .................
@@ -69,6 +83,13 @@ Other changes
 
    .. _job003756: https://www.ravenbrook.com/project/mps/issue/job003756/
 
+#. :ref:`pool-ams` pools get reliably collected, even in the case
+   where an AMS pool is the only pool on its generation chain and is
+   allocating into some generation other than the nursery. See
+   job003771_.
+
+   .. _job003771: https://www.ravenbrook.com/project/mps/issue/job003771/
+
 
 
 .. _release-notes-1.113:

mps/manual/source/topic/collection.rst

@@ -57,9 +57,9 @@ Create a generation chain by preparing an array of
 kilobytes) and *predicted mortality* (between 0 and 1) of each
 generation, and passing them to :c:func:`mps_chain_create`.
 
-When the size of the generation exceeds the capacity, the MPS will be
-prepared to start collecting the generation. See
-:ref:`topic-collection-schedule` below.
+When the *new size* of a generation exceeds its capacity, the MPS will
+be prepared to start collecting the chain to which the generation
+belongs. See :ref:`topic-collection-schedule` below.
 
 For example::
 
@@ -163,20 +163,19 @@ size* of each generation (other than the topmost) is the same as its
 total size, but in pools like :ref:`pool-ams` where survivors do not
 get promoted, the two sizes can be different.
 
-The first generation in a pool's chain is the :term:`nursery space`.
-When the nursery's *new size* exceeds its capacity, the MPS considers
-collecting the pool. (How long it takes to get around to it depends on
-which other collections on other pools are in progress.)
+When a generation's *new size* exceeds its capacity, the MPS considers
+collecting the chain to which the generation belongs. (How long it
+takes to get around to it depends on which other collections are in
+progress.)
 
 .. note::
 
-    You can affect the decision as to when to collect the nursery
-    space by using the :ref:`ramp allocation pattern
-    <topic-pattern-ramp>`.
+    You can affect the decision as to when to collect the chain 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.
+If the MPS decides to collect a chain, all generations are collected
+up to, and including, the highest generation whose *new size* exceeds
+its capacity.
 
 In pools such as :ref:`pool-amc`, blocks in generation *g* that
 survive collection get promoted to generation *g*\+1. If the last

mps/manual/source/topic/pattern.rst

@@ -110,10 +110,22 @@ cutoff and decline in the live size.
 
 This pattern is useful if you are building a structure that involves
 temporarily allocating much more memory than will fit into your
-:term:`nursery generation`. The ramp allocation pattern causes the
-collection of the nursery generation to be deferred until the ramp
+:term:`nursery generation`. By applying the ramp allocation pattern,
+the collection of that generation can be deferred until the ramp
 allocation is over.
 
+In detail: if the ramp allocation pattern is applied to an
+:term:`allocation point`, then allocation on that AP is ignored by the
+MPS when it is deciding whether to schedule a collection of the chain
+containing the generation into which the AP is allocating. See :ref:`topic-collection-schedule`.
+
+.. note::
+
+    This does not prevent the generation from being collected
+    altogether: there may be other APs allocating into the generation,
+    or the MPS may have to collect the generation in order to avoid
+    running out of memory.
+
 .. note::
 
     Ramp allocation is only supported by :ref:`pool-amc`.