From 1231d6982f0af12dfd434db43803f7146bf30fa7 Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Wed, 10 Oct 2012 22:55:40 +0100 Subject: [PATCH] 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 | 68 +++++++- mps/manual/source/pool/index.rst | 5 + mps/manual/source/pool/pool-amcz.rst | 5 + mps/manual/source/topic/format.rst | 217 ++++++++++++++++++++++++++ mps/manual/source/topic/index.rst | 6 +- mps/manual/source/topic/message.rst | 20 +++ mps/manual/source/topic/plinth.rst | 9 ++ mps/manual/source/topic/scanning.rst | 57 +++++++ mps/manual/source/topic/telemetry.rst | 5 + 9 files changed, 387 insertions(+), 5 deletions(-) create mode 100644 mps/manual/source/pool/pool-amcz.rst create mode 100644 mps/manual/source/topic/format.rst create mode 100644 mps/manual/source/topic/message.rst create mode 100644 mps/manual/source/topic/plinth.rst create mode 100644 mps/manual/source/topic/telemetry.rst diff --git a/mps/manual/source/glossary.rst b/mps/manual/source/glossary.rst index 81d45e52e4b..546c953c520 100644 --- a/mps/manual/source/glossary.rst +++ b/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 ` 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 ?? diff --git a/mps/manual/source/pool/index.rst b/mps/manual/source/pool/index.rst index df7d78db09b..ef24b36151c 100644 --- a/mps/manual/source/pool/index.rst +++ b/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 + here diff --git a/mps/manual/source/pool/pool-amcz.rst b/mps/manual/source/pool/pool-amcz.rst new file mode 100644 index 00000000000..1fc87e27bc1 --- /dev/null +++ b/mps/manual/source/pool/pool-amcz.rst @@ -0,0 +1,5 @@ +.. _pool-amcz: + +========= +AMCZ pool +========= diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst new file mode 100644 index 00000000000..7058da9f011 --- /dev/null +++ b/mps/manual/source/topic/format.rst @@ -0,0 +1,217 @@ +.. _topic-format: + +============== +Object formats +============== + + +

Example

+ +
+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, &my_scan, &my_skip, &my_copy, &my_fwd,
+                              &my_isfwd, &my_pad };
+
+  res = mps_fmt_create_A(&my_format, arena, &my_format_A);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+
+ + + + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_B_s my_format_B = { my_alignment, &my_scan, &my_skip, &my_copy,
+                              &my_fwd, &my_isfwd, &my_pad, &my_class };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_B(&my_format, arena, &my_format_B);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+
+ + + +

Example

+ +
+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, &my_scan, &my_skip, &my_fwd,
+                                        &my_isfwd, &my_pad, HEADER_SIZE };
+
+  res = mps_fmt_create_auto_header(&format, arena, &format_desc);
+  assert(res != MPS_RES_OK);
+
+  return format;
+}
+
+ + + + +

Example

+ +
+mps_addr_t my_class_method(mps_addr_t object) {
+  my_object_generic_t generic_object = object;
+  return (mps_addr_t)(generic_object.class);
+}
+
+ + + + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_A_s my_format_A = { my_alignment, &my_scan, &my_skip, &my_copy,&my_fwd,
+    &my_isfwd, &my_pad };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_A(&my_format, arena, &my_format_A);
+  if(res != MPS_RES_OK) {
+    fprintf(stderr, "Couldn't create format.\n");
+    exit(1);
+  }
+
+  return my_format;
+}
+
+ + + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_B_s my_format_B = { my_alignment, &my_scan, &my_skip, &my_copy,
+                              &my_fwd, &my_isfwd, &my_pad, &my_class };
+  mps_fmt my_format;
+  mps_res_t res;
+
+  res = mps_fmt_create_B(&my_format, arena, &my_format_B);
+  assert(res != MPS_RES_OK);
+
+  return my_format;
+}
+
+ + + + +

Example

+ +
+mps_fmt_t create_format(mps_arena_t arena)
+{
+  mps_fmt_auto_header_s format_desc = { my_alignment, &my_scan, &my_skip, &my_fwd,
+    &my_isfwd, &my_pad, HEADER_SIZE };
+  mps_fmt format;
+  mps_res_t res;
+
+  res = mps_fmt_create_auto_header(&format, arena, &format_desc);
+  assert(res != MPS_RES_OK);
+
+  return format;
+}
+
+ + + + + +

Example

+ +
+/* 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. */
+
+ + + + +

Example

+ +
+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->length));
+}
+
+ + + + +

Example

+ +
+#include "mps.h"
+#include "mpscamc.h"
+#include <stdlib.h>
+
+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(&format, space, &mps_fmt_A_s);
+  if(res != MPS_RES_OK)
+    abort();
+
+  res = mps_pool_create(&pool, space, mps_class_amc(), format);
+  if(res != MPS_RES_OK)
+    abort();
+
+  /* do some stuff here */
+
+  mps_pool_destroy(pool);
+  mps_format_destroy(format);
+}
+
diff --git a/mps/manual/source/topic/index.rst b/mps/manual/source/topic/index.rst index 36da0f8ce07..d3efc1b0ef4 100644 --- a/mps/manual/source/topic/index.rst +++ b/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 diff --git a/mps/manual/source/topic/message.rst b/mps/manual/source/topic/message.rst new file mode 100644 index 00000000000..c6bf867c32a --- /dev/null +++ b/mps/manual/source/topic/message.rst @@ -0,0 +1,20 @@ +.. _topic-message: + +======== +Messages +======== + + + + +

Example

+ +
+  mps_message_t message;
+  mps_clock_t posted_at;
+
+  if(mps_message_get(&message, arena, mps_message_type_gc_start())) {
+    posted_at = mps_message_clock(arena, message);
+    printf("Collection started at %ul.\n", (unsigned long)posted_at);
+  }
+
diff --git a/mps/manual/source/topic/plinth.rst b/mps/manual/source/topic/plinth.rst new file mode 100644 index 00000000000..3b82ccb82f2 --- /dev/null +++ b/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. diff --git a/mps/manual/source/topic/scanning.rst b/mps/manual/source/topic/scanning.rst index 7521b30dc46..a97d67f0c0d 100644 --- a/mps/manual/source/topic/scanning.rst +++ b/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) } + + + + + +

Example

+ +
+/* 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 < limit;) { /* obj maps over the objects to scan */
+    switch(((Object*)obj)->type) {
+    case ArrayType:
+      {
+        size_t i;
+        Array *array = (Array *)obj;
+
+        for(i = 0; i < array->length; ++i) { /* fix each element */
+          res = MPS_FIX12(ss, &array->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->size; i > 0; --i) { /* fix each local var */
+          res = MPS_FIX12(ss, &frame->locals[i]);
+          if(res != MPS_RES_OK) return res;
+        }
+
+        res = MPS_FIX12(ss, &frame->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;
+}
+
diff --git a/mps/manual/source/topic/telemetry.rst b/mps/manual/source/topic/telemetry.rst new file mode 100644 index 00000000000..f3cd615f141 --- /dev/null +++ b/mps/manual/source/topic/telemetry.rst @@ -0,0 +1,5 @@ +.. _topic-telemetry: + +========= +Telemetry +=========