Continue converting the reference manual to restructured text, creating topic and pool pages as needed. now 56% of the way through.

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

mps/manual/source/glossary.rst

@@ -43,7 +43,7 @@ Glossary
 
         ??
 
-    automatic pool class
+    automatic
 
         ??
 
@@ -59,6 +59,10 @@ Glossary
 
         ??
 
+    class method
+
+        ??
+
     class structure
 
         ??
@@ -83,6 +87,14 @@ Glossary
 
         ??
 
+    copy method
+
+        ??
+
+    copying
+
+        ??
+
     data object
 
         ??
@@ -99,6 +111,10 @@ Glossary
 
         ??
 
+    finalized object
+
+        ??
+
     format method
 
         ??
@@ -111,6 +127,18 @@ Glossary
 
         ??
 
+    forward method
+    
+        ??
+
+    forwarded object
+
+        ??
+
+    forwarding marker
+
+        ??
+
     fragmentation
 
         ??
@@ -123,11 +151,19 @@ Glossary
 
         ??
 
+    header
+
+        ??
+
+    is-forwarded method
+    
+        ??
+
     live
 
         ??
 
-    manual pool class
+    manual
 
         ??
 
@@ -139,6 +175,18 @@ Glossary
 
         ??
 
+    message
+
+        ??
+
+    moving
+
+        ??
+
+    non-moving
+
+        ??
+
     object
 
         A contiguous region of memory forming a single logical structure.
@@ -151,6 +199,10 @@ Glossary
 
         ??
 
+    padding method
+
+        ??
+
     padding object
 
         ??
@@ -163,6 +215,10 @@ Glossary
 
         ??
 
+    plinth
+
+        ??
+
     pointer
 
         ??
@@ -219,11 +275,11 @@ Glossary
 
         ??
 
-    scan function
+    scan method
 
         A function that examines a block of memory to find
         :term:`references <reference>` and indicate them to the MPS. A
-        scan function forms part of an :term:`object format`. See
+        scan method forms part of an :term:`object format`. See
         the topic :ref:`topic-scanning`.
 
     scan state
@@ -246,6 +302,10 @@ Glossary
 
         ??
 
+    skip method
+    
+        ??
+
     spare commit limit
 
         ??

mps/manual/source/pool/index.rst

@@ -6,6 +6,11 @@ Pool reference
    :maxdepth: 2
 
    pool-amc
+   pool-amcz
    pool-mvff
    pool-mvt
    pool-snc
+
+
+.. probably want to include
+   <https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mmdoc/doc/mps/guide/pool-classes/> here

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

@@ -0,0 +1,5 @@
+.. _pool-amcz:
+
+=========
+AMCZ pool
+=========

mps/manual/source/topic/format.rst

@@ -0,0 +1,217 @@
+.. _topic-format:
+
+==============
+Object formats
+==============
+
+
+<h4>Example</h4>
+
+<pre>
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt my_format;
+  mps_res_t res;
+  mps_fmt_A_s my_format_A = { my_alignment, &amp;my_scan, &amp;my_skip, &amp;my_copy, &amp;my_fwd,
+                              &amp;my_isfwd, &amp;my_pad };
+
+  res = mps_fmt_create_A(&amp;my_format, arena, &amp;my_format_A);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+</pre>
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_B_s my_format_B = { my_alignment, &amp;my_scan, &amp;my_skip, &amp;my_copy,
+                              &amp;my_fwd, &amp;my_isfwd, &amp;my_pad, &amp;my_class };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_B(&amp;my_format, arena, &amp;my_format_B);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+</pre>
+
+
+
+<h4>Example</h4>
+
+<pre>
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt format;
+  mps_res_t res;
+  mps_fmt_auto_header_s format_desc = { my_alignment, &amp;my_scan, &amp;my_skip, &amp;my_fwd,
+                                        &amp;my_isfwd, &amp;my_pad, HEADER_SIZE };
+
+  res = mps_fmt_create_auto_header(&amp;format, arena, &amp;format_desc);
+  assert(res != MPS_RES_OK);
+
+  return format;
+}
+</pre>
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+mps_addr_t my_class_method(mps_addr_t object) {
+  my_object_generic_t generic_object = object;
+  return (mps_addr_t)(generic_object.class);
+}
+</pre>
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_A_s my_format_A = { my_alignment, &amp;my_scan, &amp;my_skip, &amp;my_copy,&amp;my_fwd,
+    &amp;my_isfwd, &amp;my_pad };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_A(&amp;my_format, arena, &amp;my_format_A);
+  if(res != MPS_RES_OK) {
+    fprintf(stderr, "Couldn't create format.\n");
+    exit(1);
+  }
+
+  return my_format;
+}
+</pre>
+
+
+
+<h4>Example</h4>
+
+<pre>
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_B_s my_format_B = { my_alignment, &amp;my_scan, &amp;my_skip, &amp;my_copy,
+                              &amp;my_fwd, &amp;my_isfwd, &amp;my_pad, &amp;my_class };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_B(&amp;my_format, arena, &amp;my_format_B);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+</pre>
+
+
+ 
+
+<h4>Example</h4>
+
+<pre>
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_auto_header_s format_desc = { my_alignment, &amp;my_scan, &amp;my_skip, &amp;my_fwd,
+    &amp;my_isfwd, &amp;my_pad, HEADER_SIZE };
+  mps_fmt format;
+  mps_res_t res;
+
+  res = mps_fmt_create_auto_header(&amp;format, arena, &amp;format_desc);
+  assert(res != MPS_RES_OK);
+
+  return format;
+}
+</pre>
+
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+/* define the function */
+
+void example_fwd(mps_addr_t old, mps_addr_t new)
+{
+  /* ... */
+}
+
+/* also define example_scan, example_skip, etc */
+/* store pointer to function in the format variant struct */
+struct mps_fmt_B_s example_fmt_B = {
+  4, /* align */
+  example_scan,
+  example_skip,
+  example_copy,
+  example_fwd,
+  example_isfwd,
+  example_pad,
+  example_class
+};
+
+/* The (address of the) example_fmt_B object can now be passed to */
+/* mps_fmt_create_B to create a format. */
+</pre>
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+mps_addr_t my_skip_method(mps_addr_t object)
+{
+  char *p = (char *)object;
+  my_object_t my_object = (my_object_t)object;
+  return((mps_addr_t)(p + my_object-&gt;length));
+}
+</pre>
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+#include "mps.h"
+#include "mpscamc.h"
+#include &lt;stdlib.h&gt;
+
+struct mps_fmt_A_s fmt_A_s = {
+  (mps_align_t)4,
+  scan, skip, copy, move, isMoved, pad
+};
+
+void go(mps_space_t space)
+{
+  mps_fmt_t format;
+  mps_res_t res;
+  mps_pool_t pool;
+
+  res = mps_fmt_create_A(&amp;format, space, &amp;mps_fmt_A_s);
+  if(res != MPS_RES_OK)
+    abort();
+
+  res = mps_pool_create(&amp;pool, space, mps_class_amc(), format);
+  if(res != MPS_RES_OK)
+    abort();
+
+  /* do some stuff here */
+
+  mps_pool_destroy(pool);
+  mps_format_destroy(format);
+}
+</pre>

mps/manual/source/topic/index.rst

@@ -8,11 +8,15 @@ Topic reference
     arena
     allocation
     error
+    format
     scanning
     moving
     root
     cache
-    platform
     pattern
     frame
     finalization
+    plinth
+    platform
+    telemetry
+    message

mps/manual/source/topic/message.rst

@@ -0,0 +1,20 @@
+.. _topic-message:
+
+========
+Messages
+========
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+  mps_message_t message;
+  mps_clock_t posted_at;
+
+  if(mps_message_get(&amp;message, arena, mps_message_type_gc_start())) {
+    posted_at = mps_message_clock(arena, message);
+    printf("Collection started at %ul.\n", (unsigned long)posted_at);
+  }
+</pre>

mps/manual/source/topic/plinth.rst

@@ -0,0 +1,9 @@
+.. _topic-plinth:
+
+==========
+The plinth
+==========
+
+
+
+The example ANSI plinth, mpsliban.c, implements :c:func:`mps_clock` by calling ISO C time.h's clock().  The difference between two of these clock values may be converted to seconds by dividing by ISO C time.h's CLOCKS_PER_SEC conversion factor.

mps/manual/source/topic/scanning.rst

@@ -128,3 +128,60 @@ mps_res_t scan_array(mps_ss_t ss, mps_addr_t object, size_t length)
 }
 </pre>
 
+
+
+
+
+
+<h4>Example</h4>
+
+<pre>
+/* Scanner for a simple Scheme-like language with just two interesting types */
+
+mps_res_t scan_objs(mps_ss_t ss, mps_addr_t base, mps_addr_t limit)
+{
+  mps_res_t res;
+  mps_addr_t obj;
+
+  MPS_SCAN_BEGIN(ss)
+  for(obj = base; obj &lt; limit;) { /* obj maps over the objects to scan */
+    switch(((Object*)obj)-&gt;type) {
+    case ArrayType:
+      {
+        size_t i;
+        Array *array = (Array *)obj;
+
+        for(i = 0; i &lt; array-&gt;length; ++i) { /* fix each element */
+          res = MPS_FIX12(ss, &amp;array-&gt;contents[i]);
+          if(res != MPS_RES_OK) return res;
+        }
+
+        obj = AddrAdd(obj, ArraySize(array)); /* move to next object */
+        break;
+      }
+
+    case StackFrameType:
+      {
+        StackFrame *frame = (StackFrame *)obj;
+        for(i = frame-&gt;size; i &gt; 0; --i) { /* fix each local var */
+          res = MPS_FIX12(ss, &amp;frame-&gt;locals[i]);
+          if(res != MPS_RES_OK) return res;
+        }
+
+        res = MPS_FIX12(ss, &amp;frame-&gt;next);
+        if(res != MPS_RES_OK) return res;
+        obj = AddrAdd(obj, StackFrameSize(frame));
+        break;
+      }
+
+    default: /* other types don't contain references */
+      obj = AddrAdd(obj, DefaultSize(obj));
+      break;
+
+    }
+  }
+  MPS_SCAN_END(ss);
+
+  return res;
+}
+</pre>

mps/manual/source/topic/telemetry.rst

@@ -0,0 +1,5 @@
+.. _topic-telemetry:
+
+=========
+Telemetry
+=========