From 300370fa6322cd464663ab3ccc815966a31eba0f Mon Sep 17 00:00:00 2001
From: Gareth Rees <gdr@ravenbrook.com>
Date: Tue, 16 Jul 2013 10:45:05 +0100
Subject: [PATCH] Improve allocation example so that it demonstrate aligning up
 the size. explain why the mps doesn't do this for you. fix typo in scanning
 chapter.

Copied from Perforce
 Change: 183051
 ServerID: perforce.ravenbrook.com
---
 mps/manual/source/topic/allocation.rst | 20 +++++++++++++++-----
 mps/manual/source/topic/scanning.rst   |  2 +-
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/mps/manual/source/topic/allocation.rst b/mps/manual/source/topic/allocation.rst
index d6d488e70dc..6ade66050ed 100644
--- a/mps/manual/source/topic/allocation.rst
+++ b/mps/manual/source/topic/allocation.rst
@@ -243,18 +243,28 @@ is thus::
 
     mps_addr_t p;
     obj_t obj;
+    size_t aligned_size = ALIGN(size); /* see note 1 */
     do {
-        mps_res_t res = mps_reserve(&p, ap, size);
+        mps_res_t res = mps_reserve(&p, ap, aligned_size);
         if (res != MPS_RES_OK) /* handle the error */;
         /* p is now an ambiguous reference to the reserved block */
         obj = p;
         /* initialize obj */
-    } while (!mps_commit(ap, p, size));
+    } while (!mps_commit(ap, p, aligned_size)); /* see note 2 */
     /* obj is now valid and managed by the MPS */
 
-It is not necessary to worry about going around this loop many times:
-:c:func:`mps_commit` can fail at most once per thread per
-:term:`flip`.
+.. note::
+
+    1. Here :c:func:`ALIGN` represents a function or macro that
+       rounds ``size`` up to the necessary alignment, which should be
+       at least as big as the alignment of the pool. (The reason that
+       the MPS does not do this rounding up for you is to provide more
+       opportunities for optimization: in many cases the required
+       alignment will be a constant that's known at compilation time.)
+
+    2. It is not necessary to worry about going around this loop many
+       times: :c:func:`mps_commit` can fail at most once per thread
+       per :term:`flip`.
 
 
 .. c:function:: mps_res_t mps_reserve(mps_addr_t *p_o, mps_ap_t ap, size_t size)
diff --git a/mps/manual/source/topic/scanning.rst b/mps/manual/source/topic/scanning.rst
index 53dcd52cdda..36a3ecd20bf 100644
--- a/mps/manual/source/topic/scanning.rst
+++ b/mps/manual/source/topic/scanning.rst
@@ -212,7 +212,7 @@ The MPS does not require you to :term:`fix` all your :term:`references`. But if
 
 These optimizations can be tricky to make correct, and can make the
 system fragile (for example, it may break if you start using a
-different :term:`pool class`), so it usually safest to fix all
+different :term:`pool class`), so it is usually safest to fix all
 references.