MPS Wiki: Reference Manual Addenda

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

Introduction

This is a temporary collection of addenda (additions and corrections) that should go into the reference manual (RefMan). It is much better to put corrections straight into the reference manual (if possible), instead of here.

...But sometimes you need to collect information, of which some should go to RefMan and some should go into design docs etc. You can collect that sort of information here.

...And sometimes it really doesn't seem that all this information should be part of the declared public interface.

Addenda

new parameter "chain" required for `mps_class_amc`, `mps_class_ams`

Create a chain with mps_chain_create, and pass it as argument to mps_pool_create for these two pool classes.

Pool class AMS is non-generational, and must have a chain with one element ('generation') specifying a capacity and predicted mortality. This capacity is not a limit: it is only used to prompt collection of the AMS objects.

Pool class AMC is generational: the chain specifies capacity and predicted mortality of each generation. These capacities are not limits: they are used for scheduling collection of the AMC objects.

The way chains affect garbage collection is discussed in the GC Story article.

new functions: `mps_arena_step`, `mps_arena_start_collect`

When the client has some idle-time, it is permitted to call mps_arena_step(arena, interval, multiplier) to allow MPS to do collection work. The "interval" argument (units: seconds) specifies how much time the MPS is permitted to take with this mps_arena_step call. The "multiplier" argument specifies how many further similar calls to mps_arena_step the Client expects to make in this period of idle time. The idea is that the MPS should return before "interval" is exhausted, and should only eagerly commence long-duration operations that consume CPU (such as a full collection) if those operations are expected to be completed within "multiplier * interval" seconds.

Note that mps_arena_step will still step, even if the arena has been clamped. This is to allow a client to advance a collection only at these mps_arena_step points (but note that barrier hits will also cause collection work).

The client is permitted to request a full collection with mps_arena_start_collect. This is an 'asynchronous' request: the MPS returns from this call quickly, usually before the full collection has completed. (Contrast the mps_arena_collect call, which does not return until the full collection has completed). Work on the full collection then proceeds incrementally, just as it does when the MPS schedules a full collection automatically.

Fuller documentation is currently only in email. See:

new class: `mps_class_mv`

Required header: mpscmv.h

Not really new of course, just not documented before.

The Pool Class MV (Manual Variable) is a manually managed pool that manages blocks of a variable size. It is general purpose pool suitable for malloc/free style management.

Pool Class MV supports the mps_alloc/mps_free protocol.

Additional arguments to mps_pool_create. This class takes three extra arguments each one a size_t: extendBy, avgSize, maxSize. extendBy must be smaller than maxSize. (aside: this is deliberately vague, partly because the interface is rubbish)

B. Document History

  2006-11-28  RHSK  Created: chain for AMC and AMS; mps_arena_step 
                    and mps_arena_start_collect.
  2006-12-29  RHSK  More comments on chain and arena_start/_step.
  2007-04-13  DRJ   mps_class_mv
  2010-02-10  RHSK  Clarify in what way mps_arena_start_collect is 'asynchronous'

C. Copyright and License

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

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
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.