1. Choosing a pool class

This section contains a simple procedure for choosing a pool class based on the properties of the data you plan to store in it. The MPS works well if you can segregate your data into a variety of pools, choosing the most appropriate pool class for each.

Note

Pool classes can differ in many ways not considered here: speed, vulnerability to fragmentation, control overhead, and so on. This procedure gives you a decent recommendation, but an expert in the MPS might be able to make a better recommendation. And if no pool class in the open source MPS exactly matches your needs, then it is possible to develop new pool classes. See Writing a new pool class.

First, do you need the MPS to automatically reclaim unreachable blocks? If so, you need an automatically managed (garbage collected) pool class and you should consult Choosing an automatic pool class below. Otherwise, you need a manually managed pool class and you should consult Choosing a manual pool class below.

1.1. Choosing an automatic pool class

Answer these questions about your data:

  1. Is it acceptable for the MPS to move blocks in memory and to place barriers (1) on blocks? (For example, it might not be acceptable to move a block if it has been passed to foreign code that remembered its location.)

  2. Do your blocks contain references to blocks stored in automatically managed pools (including references to other blocks in the same pool, if it’s automatically managed)? And if so, are these references exact or weak?

Second, look up your answers in this table to find the recommended pool class to use:

Movable & protectable?

References?

Use this pool class

yes

none

AMCZ (Automatic Mostly-Copying Zero-rank)

yes

exact

AMC (Automatic Mostly-Copying)

yes

weak

AWL (Automatic Weak Linked)

no

none

LO (Leaf Object)

no

exact

AMS (Automatic Mark and Sweep)

no

weak

nothing suitable

1.2. Choosing a manual pool class

Answer these questions about your data:

  1. Are the blocks fixed in size? If so, use MFS (Manual Fixed Small).

  2. Are the lifetimes of blocks predictable? If so, use MVT (Manual Variable Temporal), and arrange that objects that are predicted to die at about the same time are allocated from the same allocation point.

  3. Otherwise, use MVFF (Manual Variable First Fit).

2. Pool class properties

This table summarizes the properties of each pool class provided by the open source MPS. For “block” properties, “yes” means that the property holds for all blocks allocated from the pool. An entry “—” indicates that a property makes no sense for a pool class: for example, if blocks in a pool may not contain references, it makes no sense to ask whether they may contain weak references (1).

Property

AMC

AMCZ

AMS

AWL

LO

MFS

MVFF

MVT

SNC

Supports mps_alloc()?

no

no

no

no

no

yes

yes

no

no

Supports mps_free()?

no

no

no

no

no

yes

yes

yes

no

Supports allocation points?

yes

yes

yes

yes

yes

no

yes

yes

yes

Manages memory using allocation frames?

no

no

no

no

no

no

no

no

yes

Supports segregated allocation caches?

no

no

no

no

no

yes

yes

no

no

Timing of collections? 2

auto

auto

auto

auto

auto

May contain references? 3

yes

no

yes

yes

no

no

no

no

yes

May contain exact references? 4

yes

yes

yes

yes

May contain ambiguous references? 4

no

no

no

no

May contain weak references? 4

no

no

yes

no

Allocations fixed or variable in size?

var

var

var

var

var

fixed

var

var

var

Alignment? 5

conf

conf

conf

conf

conf

6

7

7

conf

Dependent objects? 8

no

no

yes

no

May use remote references? 9

no

no

no

no

Blocks are automatically managed? 10

yes

yes

yes

yes

yes

no

no

no

no

Blocks are promoted between generations

yes

yes

no

no

no

Blocks are manually managed? 10

no

no

no

no

no

yes

yes

yes

yes

Blocks are scanned? 11

yes

no

yes

yes

no

no

no

no

yes

Blocks support base pointers only? 12

no

no

yes

yes

yes

yes

Blocks support internal pointers? 12

yes

yes

no

no

no

no

Blocks may be protected by barriers?

yes

no

yes

yes

yes

no

no

no

yes

Blocks may move?

yes

yes

no

no

no

no

no

no

no

Blocks may be finalized?

yes

yes

yes

yes

yes

no

no

no

no

Blocks must be formatted? 11

yes

yes

yes

yes

yes

no

no

no

yes

Blocks may use in-band headers?

yes

yes

yes

yes

yes

no

Notes

2

“Timing of collections” is “auto” if garbage collection is under the control of the MPS, which decides when collection should take place and performs it automatically and incrementally.

3

The references in question are references to blocks in automatically managed pools.

4(1,2,3)

Pools “may contain ambiguous / exact / weak references” if the references that the client program fixes during scanning may include references of the indicated rank.

5

“Alignment” is “conf” if the client program may specify alignment for each pool.

6

The alignment of blocks allocated from MFS (Manual Fixed Small) pools is the platform’s natural alignment, MPS_PF_ALIGN.

7(1,2)

MVT (Manual Variable Temporal) and MVFF (Manual Variable First Fit) pools have configurable alignment, but it may not be smaller than sizeof(void*).

8

In pools with this property, each object may specify an dependent object which the client program guarantees will be accessible during the scanning of the first object. This may be used in the implementation of weak hash tables.

9

“Remote references” are references that are stored outside the block to which they logically belong (for example, in some kind of auxiliary table). A pool containing remote references cannot rely on a write barrier to detect changed references.

10(1,2)

Blocks are “automatically managed” if they may be automatically discarded when the MPS determines that they are unreachable; they are “manually managed” if they can be discarded when the client program requests it. Note that these properties are not mutually exclusive, although the MPS does not provide a pool class that satisfies both.

11(1,2)

Blocks “are scanned” if the MPS scans them for references; blocks “must be formatted” if they are described to the MPS by an object format. At present, the MPS only knows how to scan blocks using the scan method from an object format, but the MPS design does not preclude pools that scan unformatted blocks.

12(1,2)

A block “supports internal pointers” if a pointer to any location within the block is considered to be a reference to the block. It “supports base pointers only” if only a pointer to the base of the block (or, if the block belongs to an object format with in-band headers, a pointer just past the end of the header) is considered to be a reference to the block.

Pools that support internal pointers can be switched to base pointers only, by setting the optional keyword argument MPS_KEY_INTERIOR to FALSE when calling mps_pool_create_k().

3. Writing a new pool class

If none of the pool classes supplied with the MPS are quite right for your application, don’t despair: the MPS is designed to be extensible with new pool classes, and designed so that the properties of pools are as orthogonal as possible. So if you need a pool containing objects that are scannable but unformatted, or movable objects which are manually managed, or a pool all of whose objects are roots, there is no technical reason why it should not be possible to write it.

If you’d be interested in our developing new pool classes for your requirements, or if you’ve started writing a new pool class yourself, we’d love to hear from you.