diff --git a/mps/manual/wiki/gc.html b/mps/manual/wiki/gc.html index d5baded3a95..e30a2e5f0c7 100644 --- a/mps/manual/wiki/gc.html +++ b/mps/manual/wiki/gc.html @@ -42,14 +42,107 @@

This wiki article contains incomplete and informal notes about the MPS, the precursor to more formal documentation. Not confidential. Readership: MPS users and developers.

-
-Notes on getting started with GC -- Garbage Collection.
-
+

Notes on getting started with GC -- Garbage Collection.

+ +

Introduction

+ +

The essential MPS concepts for GC are:

+ + +

Formats

+ +

The client can choose how to format its objects, but the MPS will +sometimes need to ask the client some questions about an object, such +as:

+ + +

For each type of question, the client must provide a function that gives +the answer. These functions collected together are called 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().

+ +

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 +allowed to do. Format code is often on the critial path for memory +management operations. The full requirement for a format is +complicated; see pool class documentation in the Reference Manual. But +here's a simplified overview:

+ +

No format is required for an object in a non-scanned, non-collectable +pool -- the MPS never needs to know the internal details of objects in +these pools.

+ +

For collectable and/or scannable pools, the client's format code +generally needs to support three types of object:

+
    +
  1. the client's own initialized objects;
  2. +
  3. on behalf of the MPS, a "forwarding object";
  4. +
  5. on behalf of the MPS, a "padding object".
  6. +
+ +

A forwarding object is a placeholder that the MPS uses when it has moved +the object that used to be there. ('Normal' client code never sees +these forwarding objects; only client format code does).

+ +

A padding object is a 'dummy' object that the MPS uses when there is not +enough room (eg. at the end of a memory page) to put a real client +object.

+ +

The client must be able to distinguish between these three types +of object. To guarantee this, client code MUST initialize +memory returned by the MPS (by mps_alloc() or mps_reserve()) BEFORE it +makes any other call into the MPS from that thread (including the call to +mps_commit). Here, "initialize" means at least enough initialization +that the client's format code handles the object correctly, including +whether it is a client object, a forwarding object, or a padding object. +[See also protocol.mps.format.rel.ap. RHSK 2006-06-02]

+ +

The most important format methods are:

+ +

To support collectable client objects:

+ + +

To support movable client objects:

+ + +

To support forwarding objects (once a movable client object has been moved):

+ + +

To support padding objects:

+

B. Document History

   2006-06-02  RHSK  Created.
+  2006-06-02  RHSK  Introduction to MPS Formats