GC Messages

1. Introduction

This document describes the design of a set of MPS message classes. The messages from these classes are emitted according to various important phases in a GC cycle; collectively they are called GC Messages.

The current classes are:

mps_message_type_gc_start()

(new in gcgenmsg branch) These messages are generated once per GC at the start of a GC.

mps_message_type_gc()

These messages are generated once per GC at the end of a GC.

The intended readership is project staff.

This document is not confidential.

2. Background, MPS messages and collections

This needs filling in. Taken as read and understood for now.

Note that some of the implementation (of mps_message_type_gc) pre-dates this design; it may not be documented accurately (or at all) here.

3. Requirements

The primary requirement is:

  • MPS staff must be able to tell what collections are happening in order to be able to introspect about the overall MPS process.

    This is so that bugs can be diagnosed and general MPS behaviour can be reasoned about. A typical problem is that a customer reports "Why when this collection happens doesn't this 20 MB of garbage get collected?". At a minimum we need to know what was condemned in any particular collection; it useful to know what is going to happen to survivors.

We meet part of that requirement by implementing a message that is generated per collection (mps_message_type_gc_start).

We have the following requirements on per GC messages:

  • Must be able to tell why we are starting a collection. See job000666 for why we start collections.

4. Implementation

4.2 A new per collection message class (mps_message_type_gc_start)

Messages in this class support:

  • Being able to tell why a collection is starting.

4.2.1 Message instances.

As well as TraceMessageStruct (for mps_message_type_gc) there will be a TraceStartMessageStruct. Could this be rolled into TraceMessageStruct? Not really (maybe with a redesign) as TraceMessageStruct is dynamically allocated as the message is posted to the arena queue (at the end of the trace).

5. Interface

int mps_message_type_gc_start()

Public interface. Returns the MPS message type.

const char *mps_message_gc_start_why(mps_arena_t, mps_message_t)

Public interface. Returns a pointer to a string that is a textual explanation of why this collection is starting.

The contents of the string must not be modified by the client. The string and the pointer are only valid as long as the message has not been discarded (with mps_message_discard).

6. Testing

amcss already collects and reports mps_message_type_gc. It should be simple to extend it to mps_message_type_gc_start and mps_message_type_gc_generation.

Using amcss might not give a very good coverage. In particular not all the available reasons will appear. Perhaps a more dedicated test should be written.

7. Unimplemented mps_message_type_gc_generation

This section for historical interest only.

A proposal to more fully meet the primary requirement by implementing a message that is generated per generation per collection (mps_message_type_gc_generation) has not been implemented, but the requirements have been retained here:

We would have the following requirements on per generation messages:

  • Must be able to tell for any generation whether it is condemned for each collection that occurs. In practise, due to the flexible nature of the MPS, a generation might not be either all-condemned or all-foundation for any particular collection. In particular the commonest sort of collection (collections driven by allocation in the nursery generations) will condemn a particular set of zones. There may be generations which have some object in one zone and some objects in another; they may have only some of their objects condemned by a per zone condemnation strategy.

  • For each generation for each collection we would like to know the following:

    • Number of bytes condemned in this generation.

    • Number of bytes occupied by objects and not condemned.

    • Where survivors are going (that is, what generation are survivors are being promoted to.

    • (Not essential) Other byte counts for this generation: How much free space there is, how much overhead there is.

A. References

B. Document History

2003-02-17 DRJ Created.
2006-12-07 RHSK Remove mps_message_type_gc_generation (not implemented).
2007-02-08 RHSK Move historically interesting requirements for mps_message_type_gc_generation (not implemented) to the end of the doc.