4. AMC (Automatic Mostly-Copying)

AMC is a general-purpose automatically managed pool class. This is the most mature pool class in the MPS, intended for the majority of objects in the client program. Use this pool class unless you need a particular feature that it doesn’t provide.

“Mostly Copying” means that it uses copying garbage collection except for blocks that are pinned by ambiguous references.

It uses generational garbage collection. That is, it exploits assumptions about object lifetimes and inter-connection variously referred to as “the generational hypothesis”. In particular, the following tendencies will be efficiently exploited by an AMC pool:

• most objects die young;
• objects that don’t die young will live a long time.

In the pool’s generation chain, specify the capacity and mortality of generations 0 to n−1. Survivors from generation n−1 get promoted into an arena-wide “top” generation.

4.1. AMC properties

• Does not support allocation via mps_alloc() or deallocation via mps_free().
• Supports allocation via allocation points. If an allocation point is created in an AMC pool, the call to mps_ap_create() takes no additional parameters.
• Supports allocation frames but does not use them to improve the efficiency of stack-like allocation.
• Does not support segregated allocation caches.
• Garbage collections are scheduled automatically. See Scheduling of collections.
• Blocks may contain exact references to blocks in the same or other pools (but may not contain ambiguous references or weak references⁽¹⁾, and may not use remote references).
• Allocations may be variable in size.
• The alignment of blocks is configurable.
• Blocks do not have dependent objects.
• Blocks that are not reachable from a root are automatically reclaimed.
• Blocks are scanned.
• Blocks may only be referenced by base pointers (unless they belong to an object format of variant auto-header).
• Blocks may be protected by barriers⁽¹⁾.
• Blocks may move.
• Blocks may be registered for finalization.
• Blocks must belong to an object format.

4.2. AMC interface

#include "mpscamc.h"

mps_class_t mps_class_amc(void)

Return the pool class for an AMC (Automatic Mostly-Copying) pool.

When creating an AMC pool, mps_pool_create_k() requires two keyword arguments:

• MPS_KEY_FORMAT (type mps_fmt_t) specifies the object format for the objects allocated in the pool. The format must provide a scan method, a skip method, a forward method, an is-forwarded method and a padding method.
• MPS_KEY_CHAIN (type mps_chain_t) specifies the generation chain for the pool.

For example:

MPS_ARGS_BEGIN(args) {
    MPS_ARGS_ADD(args, MPS_KEY_CHAIN, chain);
    MPS_ARGS_ADD(args, MPS_KEY_FORMAT, fmt);
    MPS_ARGS_DONE(args);
    res = mps_pool_create_k(&pool, arena, mps_class_amc(), args);
} MPS_ARGS_END(args);

Deprecated

starting with version 1.112.

When using mps_pool_create(), pass the format and chain like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_class_t mps_class_amc(),
                          mps_fmt_t fmt,
                          mps_chain_t chain)

4.3. AMC introspection

#include "mpscamc.h"

void mps_amc_apply(mps_pool_t pool, mps_amc_apply_stepper_t f, void *p, size_t s)

Visit all formatted objects in an AMC pool.

pool is the pool whose formatted objects you want to visit.

f is a function that will be called for each formatted object in the pool.

p and s are arguments that will be passed to f each time it is called. This is intended to make it easy to pass, for example, an array and its size as parameters.

It is an error to call this function when the arena is not in the parked state. You need to call mps_arena_collect() or mps_arena_park() before calling mps_amc_apply().

The function f will be called on both client and padding objects. It is the job of f to distinguish, if necessary, between the two. It may also be called on dead objects that the collector has not recycled or has been unable to recycle.

Note

There is no equivalent function for other pool classes, but there is a more general function mps_arena_formatted_objects_walk() that visits all formatted objects in the arena.

Note

This function is intended for heap analysis, tuning, and debugging, not for frequent use in production.

void (*mps_amc_apply_stepper_t)(mps_addr_t addr, void *p, size_t s)

The type of a stepper function for formatted objects in an AMC pool.

addr is the address of an object in the pool.

p and s are the corresponding arguments that were passed to mps_amc_apply().

The function may not call any function in the MPS. It may access:

1. memory inside the object or block pointed to by addr;
2. memory managed by the MPS that is in pools that do not protect their contents;
3. memory not managed by the MPS;

It must not access other memory managed by the MPS.