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

C. Copyright and License

This document is copyright © 1995-2002, 2006-2007 Ravenbrook Limited. All rights reserved. This is an open source license. Contact Ravenbrook for commercial licensing options.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Redistributions in any form must be accompanied by information on how to obtain complete source code for the this software and any accompanying software that uses this software. The source code must either be included in the distribution or be available for no more than the cost of distribution plus a nominal fee, and must be freely redistributable under reasonable conditions. For an executable file, complete source code means the source code for all modules it contains. It does not include source code for modules or files that typically accompany the major components of the operating system on which the executable file runs.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement, are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.