ocean.util.container.pool.model.IAggregatePool

Pool of structs or classes. Adds the following features to the base class: * Iteration over all items in the pool, or all busy or idle items. (See further notes below.) * get() and fill() methods which accept a lazy parameter for a new item to be added to the pool, if needed. * For structs, and classes with a default (paramaterless) constructor, get() and fill() methods which automatically create new pool items, without requiring them to be passed via a lazy argument. * Implementation of the item index (required by IPool) as a size_t member of the item type, called 'object_pool_index'. It is required that the item type has this member.

Iteration can either be 'safe' or 'unsafe' (read-only). R/W (safe) iteration operates on an internal copy of the real pool data, thus making it safe to modify the pool during an iteration, but obviously entailing additional work due to needing to copy the data. Read-only (unsafe) iteration iterates over the actual items in the pool, meaning that it is not safe to modify the pool while iterating.

Both types of iteration are handled by scope classes which must be newed to get access to an iterator. The R/W (safe) iterator scope classes perform the required copy of the set of items to be iterated over upon construction. As the IAggregatePool instance contains a single buffer which is used to store the iteration set for safe iterators, it is only possible for a single safe iterator to be newed at a time. There are asserts in the code to enforce this. (The advantage of having the safe iterator as a scope class is that it can be newed, performing the required copy once, then used multiple times, rather then doing the copy upon every iteration, as might be the case if a simple opApply method existed.)

Iteration usage example (with ObjectPool):

import ocean.util.container.pool.ObjectPool;

void main ( )
{
    class MyClass { size_t object_pool_index; }

    auto pool = new ObjectPool!(MyClass);

    // use pool

    scope busy_items = pool.new BusyItemsIterator;

    foreach ( busy_item; busy_items )
    {
        // busy_item now iterates over the items in the pool that
        // were busy when busy_items was created.
    }
}

Important note about newing pool iterators:

Pool iterators must be newed as shown in the example above, *not* like this:

foreach ( busy_item; pool.new BusyItemsIterator )

This is because the iterators are designed as scope classes, meaning that newing them won't GC allocate (and thus can't trigger a collection). In case like the above, the absence of scope means a GC allocation.

Note about ref iteration over pools:

If the pool items are structs, 'ref' iteration is required to make the modification of the items iterated over permanent. For objects 'ref' should not be used.