From dceb030fbf9be79efabc35bfb91789fd182d93a2 Mon Sep 17 00:00:00 2001
From: Richard Kistruck <rhsk@ravenbrook.com>
Date: Tue, 6 Jun 2006 12:55:22 +0100
Subject: [PATCH] Mps wiki article on gc: mps formats: clarify explanation of
 methods, and list variants.

Copied from Perforce
 Change: 159102
 ServerID: perforce.ravenbrook.com
---
 mps/manual/wiki/gc.html | 52 +++++++++++++++++++++++++++++------------
 1 file changed, 37 insertions(+), 15 deletions(-)

diff --git a/mps/manual/wiki/gc.html b/mps/manual/wiki/gc.html
index e30a2e5f0c7..e23d7b12aa9 100644
--- a/mps/manual/wiki/gc.html
+++ b/mps/manual/wiki/gc.html
@@ -65,10 +65,12 @@ as:</p>
 </ul>
 
 <p>For each type of question, the client must provide a function that gives
-the answer.  These functions collected together are called a "format"
+the answer.  These functions are called "format methods", and are
+collected together into a "format"
 (mps_fmt_t).  Usually the client developer writes these functions,
-collects them into a format, and passes this format to the MPS as an
-argument to mps_pool_create().</p>
+calls "<code>mps_fmt_create_...</code>" to
+collect them into a format, and passes this format to the MPS as an
+argument to <code>mps_pool_create()</code>.</p>
 
 <p>A client's format code is 'special'.  It is called at special times (eg.
 when handling an interrupt), and is quite restricted in what it is
@@ -108,41 +110,61 @@ whether it is a client object, a forwarding object, or a padding object.
 
 <h3><a id="format-methods">The most important format methods are:</a></h3>
 
-<p>To support collectable client objects:</p>
+<p>Indicate the size of a collectable client object:</p>
 <ul>
   <li> Skip (see <a href="../reference/index.html#mps_fmt_skip_t">mps_fmt_skip_t</a>):
-         tell the MPS how big this object is.</li>
+         client must tell the MPS how big this object is.</li>
 </ul>
 
-<p>To support movable client objects:</p>
+<p>List all references from this object to (other) collectable objects:</p>
 <ul>
   <li> Scan (see <a href="../reference/index.html#mps_fmt_scan_t">mps_fmt_scan_t</a>): 
-         tell the MPS what other objects this object
-         refers to;</li>
-  <li> Copy (see <a href="../reference/index.html#mps_fmt_copy_t">mps_fmt_copy_t</a>):
-         copy an object to a new location.</li>
+         client must 'scan' the object for pointers, and tell 
+         the MPS to 'fix' each pointer it finds;</li>
 </ul>
 
-<p>To support forwarding objects (once a movable client object has been moved):</p>
+<p>Move this client object:</p>
+<ul>
+  <li> Copy (see <a href="../reference/index.html#mps_fmt_copy_t">mps_fmt_copy_t</a>):
+         client must copy the object to a new location.</li>
+</ul>
+
+<p>Create/use a forwarding object (used by an incremental moving collector after moving a client object):</p>
 <ul>
   <li> Fwd (see <a href="../reference/index.html#mps_fmt_fwd_t">mps_fmt_fwd_t</a>):
-         create a forwarding object here, please;</li>
+         client must create a forwarding object here, and store
+         the supplied forwarding pointer in it;</li>
   <li> IsFwd (see <a href="../reference/index.html#mps_fmt_isfwd_t">mps_fmt_isfwd_t</a>):
-         is this a forwarding object, and where 
-         did it move to?</li>
+         client must test whether this is a forwarding object
+         (created by the Fwd method), and if so return the 
+         forwarding pointer stored in it.  (This is how the 
+         MPS remembers where a moved object was moved to).</li>
 </ul>
 
-<p>To support padding objects:</p>
+<p>Create a padding object:</p>
 <ul>
   <li> Pad (see <a href="../reference/index.html#mps_fmt_pad_t">mps_fmt_pad_t</a>):
          create a padding object here, please.</li>
 </ul>
 
+<h3><a id="format-variants">Format Variants</a></h3>
+
+<p>There are several different ways to package-up the format methods -- these different ways are called 'variants'.  MPS currently supports four format variants.  The creation functions for these are:</p>
+<ul>
+  <li> <a href="../reference/index.html#mps_fmt_create_A">mps_fmt_create_A</a>;</li>
+  <li> <a href="../reference/index.html#mps_fmt_create_B">mps_fmt_create_B</a>;</li>
+  <li> <a href="../reference/index.html#mps_fmt_create_auto_header">mps_fmt_create_auto_header</a>;</li>
+  <li> <a href="../reference/index.html#mps_fmt_create_fixed">mps_fmt_create_fixed</a>.</li>
+</ul>
+
+<p>It's a bit messy -- sorry.</p>
+
 <h2><a id="section-B" name="section-B">B. Document History</a></h2>
 
 <pre>
   2006-06-02  RHSK  Created.
   2006-06-02  RHSK  Introduction to MPS Formats
+  2006-06-06  RHSK  Formats: clarify explanation of methods, and list variants.
 </pre>