Exec Item Pools

Introduction

An item pool is a special memory pool that can only allocate and deallocate predefined slabs of memory. Every allocation from this pool is exactly the same size. There are no exceptions to this rule. Allocation and deallocation of these items is typically extremely fast unless the pool needs to be enlarged or garbage collection takes place. Item pools are commonly called "slab allocators" although the latter usually also refers to a kind of allocation that leaves data intact between calls.

An item pool should be used whenever an application wants to allocate a large number of equally sized objects. For example, an application allocating a couple thousand Rectangle structures, or list items, could use an item pool for that to dramatically reduce the allocation time and memory fragmentation.

Many applications frequently allocate very similar pieces of memory, like list nodes, rectangles, or similar structures. If these items are sufficiently large, their constant allocation and deallocation will produce a potentially large amount of fragmented memory nodes.

Creating an Item Pool

You create an item pool by calling AllocSysObject() with the ASOT_ITEMPOOL object type and the item size, memory type, garbage collection policy and other options.

The item pool is created with an initial amount of item storage space and automatically extends when that space runs out. To control the maximum number of allocations allowed use the ASOITEM_MaxSize tag.

The memory type is one of MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. If your application requires memory of different types (for example, private memory and shared memory), it must create a pool for each type.

Setting MEMF_CLEAR in the memory flags will result in clearing each allocated item (prior to calling any defined constructor hook) so it might introduce a certain overhead.

If successful, AllocSysObject() returns the address of the item pool.

APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
  ASOITEM_MFlags, MEMF_PRIVATE | MEMF_CLEAR,
  ASOITEM_ItemSize, sizeof(struct Rectangle),
  TAG_END);
 
if (item_pool != NULL)
{
  // ...
}
else
  IDOS->Printf("Pool could not be created.\n");

The example above attempts to create an item pool with an item size of sizeof(struct Rectangle).

Take note that all you know about an item pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!

Garbage Collection Policy

Each item pool has a garbage collection policy associated with it. The garbage collection policy can have a negative impact on the allocation/deallocation speed of an item pool so it is important to choose the policy which is best for your specific application.

Here is an example with garbage collection disabled and the maximum number of items set to 2000. This kind of item pool would allocate items very quickly with an upper bound so that it will not eat too much memory.

APTR item_pool = IExec->AllocSysObjectTags(ASOT_ITEMPOOL,
  ASOITEM_MFlags, MEMF_PRIVATE | MEMF_CLEAR,
  ASOITEM_ItemSize, sizeof(struct Rectangle),
  ASOITEM_MaxSize, 2000,
  ASOITEM_GCPolicy, ITEMGC_NONE,
  TAG_END);

In this case, the application is responsible for manually performing garbage collection using the ItemPoolGC() function.

Allocating Memory from an Item Pool

Memory is obtained from an item pool by calling ItemPoolAlloc(). ItemPoolAlloc() requires only a pointer to the item pool and nothing more. That is because the size of every item is exactly the same as defined by the ASOITEM_ItemSize tag during pool creation. If successful, ItemPoolAlloc() returns a pointer to the memory.

struct Rectangle *rect;
 
if (rect = IExec->ItemPoolAlloc(item_pool))
{
  // ...
}
else
  IDOS->Printf("Memory could not be allocated.\n");

You must not make any assumptions about the contents of a newly created item other than having it cleared when MEMF_CLEAR is specified. Most notably, the content of an item may change when it is re-allocated.

Items within an item pool are not necessarily packed closely together. The system may adjust the item size for better cache coherency or other factors.

The optional item constructor, specified with the ASOITEM_Constructor tag, is called immediately after an item is successfully allocated. If the MEMF_CLEAR was specified, the item will have been cleared before the constructor is called.

Freeing Memory from an Item Pool

Memory is returned for use in an item pool by calling ItemPoolFree(). ItemPoolFree() requires a pointer to the item pool and the item to be freed.

IExec->ItemPoolFree(item_pool, rect);

In this example, the "rect" pointer must point to an item which was previously allocated with ItemPoolAlloc(). Items can never be reused or otherwise referenced after being freed.

The optional item destructor, specified with the ASOITEM_Destructor tag, is called immediately before an item is freed.

Deleting an Item Pool

Similar to Exec Memory Pools, all memory allocated in the item pool is delete as soon as the item pool itself is freed.

IExec->FreeSysObject(ASOT_ITEMPOOL, item_pool);