40. Transforms

40.1. Introduction

This document describes the Transform mechanism of the Memory Pool System. Transforms allow the client code to replace a set of object references on the heap.

The readership of this document is any developer intending to modify the Transform implementation.

40.2. Background

Göran Rydqvist of Configura originally expressed the requirement for the MPS to support the change of layout of objects in CET [GR_2010-02-25]. Ravenbrook proposed several methods [RHSK_2010-09-21] including:

If you need to add fields, then use a special new MPS function (that doesn’t exist yet):

mps_arena_transform_objects(&my_transform_function);

This traverses the object graph, lets your transform_function basically realloc() the field-block, and MPS fixes up all references from other objects to point to the new field-block.

Unfortunately, this idea is probably killed off by ambiguous references :-(. You could only run the patch if you could guarantee there are no ambiguous refs you want. In other words, any object refs on the stack would become instant death (or worse: subtle slow death :-). Therefore we don’t really like this idea (unfortunately). There are safer and simpler ways to do it, we think…

which Configura selected [GR_2010-09-22].

An initial implementation was made by RHSK and released to Configura as “experimental”, however Configura put it into production.

During work on adapting the MPS to 64-bit Windows, RB reformed and reimplemented transforms based on RHSK’s original work.

40.3. Overview

The client program builds a table mapping “old” references to “new” ones in a Transform object. This is then “applied”, causing a garbage collection trace in which the fix function is substituted by transformFix(), which spots “old” references and replaces them with “new” ones, in addition to applying the usual garbage collection fix function.

This design was arrived at after some pain. The MPS isn’t really designed for generalized transformation of the object graph, and the pools generally assume that they’re doing a garbage collection when they’re asked to condemn, scan, fix, and reclaim stuff. This makes it very hard to apply the transform without also doing a garbage collection. Changing this would require a significant reworking of the MPS to generalise its ideas, and would bloat the pool classes.

40.4. Not yet written

  • Ambiguous references and aborting the transform.

  • How ambiguous references are avoided using arena->stackWarm.

  • Why it does a garbage collection and not just a transforming scan. [This is partly explained in Overview above. RB 2023-06-16]

  • Nice side-effect is that “old” objects are killed.

  • Why the arena must be parked [When writing this up see impl.c.trans.park and impl.c.trans.assume.parked. RB 2023-06-16].

  • Why we can’t transform arbitrary references (see impl.c.trans.old-white).

40.5. References

[GR_2010-02-25]

“Incremental object” (e-mail); Göran Rydqvist; Configura; 2010-02-25; <https://info.ravenbrook.com/mail/2010/02/25/16-35-45/0/>.

[RHSK_2010-09-21]

“Incremental object ideas” (e-mail); Richard Kistruck; Ravenbrook Limited; 2010-09-21; <https://info.ravenbrook.com/mail/2010/09/21/16-54-59/0/>.

[GR_2010-09-22]

“Incremental object ideas” (e-mail); Göran Rydqvist; Configura; 2010-09-22; <https://info.ravenbrook.com/mail/2010/09/22/09-27-53/0/>.