6. AMS (Automatic Mark and Sweep)

AMS is an automatically managed but non-moving pool class. It should be used instead of AMC (Automatic Mostly-Copying) for blocks that need to be automatically managed, but cannot be moved.

Note

AMS is likely to be useful as a step in integrating a program with the MPS. It allows you to work on scanning (and investigate errors resulting from underscanning) without having to deal with objects moving as well. When you are confident that scanning is correct, you can switch to AMC (Automatic Mostly-Copying).

AMS is not currently suitable for production use. However, it could be developed into a solid mark-and-sweep pool. If you have a use case that needs this, contact us.

6.1. AMS 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 AMS pool, the call to mps_ap_create_k() takes no keyword arguments.

• 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.

• Does not use generational garbage collection, so blocks are never promoted out of the generation in which they are allocated.

• Blocks may contain exact references to blocks in the same or other pools, or ambiguous references (if the MPS_KEY_AMS_SUPPORT_AMBIGUOUS keyword argument is set to true when creating the pool). Blocks may not contain weak references (1), 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 have in-band headers).

• Blocks are not protected by barriers (1).

• Blocks do not move.

• Blocks may be registered for finalization.

• Blocks must belong to an object format which provides scan and skip methods.

• Blocks may have in-band headers.

6.2. AMS interface

#include "mpscams.h"

mps_class_t mps_class_ams(void)

Return the pool class for an AMS (Automatic Mark & Sweep) pool.

When creating an AMS pool, mps_pool_create_k() requires one keyword argument:

• 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 and a skip method.

It accepts three optional keyword arguments:

• MPS_KEY_CHAIN (type mps_chain_t) specifies the generation chain for the pool. If not specified, the pool will use the arena’s default chain.

• MPS_KEY_GEN (type unsigned) specifies the generation in the chain into which new objects will be allocated. If you pass your own chain, then this defaults to 0, but if you didn’t (and so use the arena’s default chain), then an appropriate generation is used.

  Note that AWL does not use generational garbage collection, so blocks remain in this generation and are not promoted.

• MPS_KEY_AMS_SUPPORT_AMBIGUOUS (type mps_bool_t, default false) specifies whether references may be ambiguous.

For example:

MPS_ARGS_BEGIN(args) {
    MPS_ARGS_ADD(args, MPS_KEY_FORMAT, fmt);
    MPS_ARGS_ADD(args, MPS_KEY_AMS_SUPPORT_AMBIGUOUS, 1);
    res = mps_pool_create_k(&pool, arena, mps_class_ams(), args);
} MPS_ARGS_END(args);

Deprecated

starting with version 1.112.

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

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_class_t mps_class_ams(),
                          mps_fmt_t fmt,
                          mps_chain_t chain,
                          mps_bool_t support_ambiguous)

When creating an allocation point on an AMS pool, mps_ap_create_k() accepts one keyword argument:

• MPS_KEY_RANK (type mps_rank_t, default mps_rank_exact()) specifies the rank of references in objects allocated on this allocation point. It must be mps_rank_exact() (if the objects allocated on this allocation point will contain exact references), or mps_rank_ambig() (if the objects may contain ambiguous references).

For example:

MPS_ARGS_BEGIN(args) {
    MPS_ARGS_ADD(args, MPS_KEY_RANK, mps_rank_ambig());
    res = mps_ap_create_k(&ap, ams_pool, args);
} MPS_ARGS_END(args);

Deprecated

starting with version 1.112.

When using mps_ap_create(), pass the rank like this:

mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool,
                        mps_rank_t rank)

mps_class_t mps_class_ams_debug(void)

A debugging version of the AMS pool class.

When creating a debugging AMS pool, mps_pool_create_k() takes three keyword arguments: MPS_KEY_FORMAT and MPS_KEY_CHAIN are as described above, and MPS_KEY_POOL_DEBUG_OPTIONS specifies the debugging options. See mps_debug_option_s.

Deprecated

starting with version 1.112.

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

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_class_t mps_class_ams_debug(),
                          mps_debug_option_s debug_option,
                          mps_fmt_t fmt,
                          mps_chain_t chain,
                          mps_bool_t support_ambiguous)