8. LO (Leaf Object)

LO is an automatically managed pool class for leaf objects (objects that contain no references). It does not move or protect its objects.

This pool class is intended for unstructured data that needs to be accessed by foreign code. It’s ideal for allocating a buffer that needs to be passed to an operating system I/O function.

Note

A thread that reads or writes from blocks allocated in this pool need not be registered with the arena so long as the liveness of the block is independent of that thread.

This means that you can launch a thread to read or write a buffer allocated in this pool, without having to register the thread, so long as you ensure that the buffer remains alive until the thread has finished (for example, by keeping a reference to the buffer in a root or a scanned object).

If LO is used to allocate large numbers of small objects, the garbage collection performance will degrade. For leaf objects that can move and be protected, it is better to use AMCZ (Automatic Mostly-Copying Zero-rank) instead.

8.1. LO 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 a LO 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 not contain references to blocks in automatically managed pools.

• 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 not scanned. A consequence of this is that the pool’s object format need not provide a scan method.

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

8.2. LO interface

#include "mpsclo.h"

mps_pool_class_t mps_class_lo(void)

Return the pool class for an LO (Leaf Object) pool.

When creating an LO 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 skip method.

It accepts two 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 LO does not use generational garbage collection, so blocks remain in this generation and are not promoted.

For example:

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