Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
a local clone.

std.experimental.allocator.building_blocks.allocator_list

Given an object factory of type Factory or a factory function
factoryFunction, and optionally also BookkeepingAllocator as a supplemental
allocator for bookkeeping, AllocatorList creates an allocator that lazily
creates as many allocators are needed for satisfying client allocation requests.

An embedded list builds a most-recently-used strategy: the most recent
allocators used in calls to either allocate, owns (successful calls
only), or deallocate are tried for new allocations in order of their most
recent use. Thus, although core operations take in theory Ο(k) time for
k allocators in current use, in many workloads the factor is sublinear.
Details of the actual strategy may change in future releases.

AllocatorList is primarily intended for coarse-grained handling of
allocators, i.e. the number of allocators in the list is expected to be
relatively small compared to the number of allocations handled by each
allocator. However, the per-allocator overhead is small so using
AllocatorList with a large number of allocators should be satisfactory as long
as the most-recently-used strategy is fast enough for the application.

AllocatorList makes an effort to return allocated memory back when no
longer used. It does so by destroying empty allocators. However, in order to
avoid thrashing (excessive creation/destruction of allocators under certain use
patterns), it keeps unused allocators for a while.

Parameters:

factoryFunction

A function or template function (including function literals).
New allocators are created by calling factoryFunction(n) with strictly
positive numbers n. Delegates that capture their enviroment are not created
amid concerns regarding garbage creation for the environment. When the factory
needs state, a Factory object should be used.

BookkeepingAllocator

Allocator used for storing bookkeeping data. The size of
bookkeeping data is proportional to the number of allocators. If BookkeepingAllocator is NullAllocator, then AllocatorList is
"ouroboros-style", i.e. it keeps the bookkeeping data in memory obtained from
the allocators themselves. Note that for ouroboros-style management, the size
n passed to make will be occasionally different from the size
requested by client code.

Factory

Type of a factory object that returns new allocators on a need
basis. For an object sweatshop of type Factory, sweatshop(n) should
return an allocator able to allocate at least n bytes (i.e. Factory must
define opCall(size_t) to return an allocator object). Usually the capacity of
allocators created should be much larger than n such that an allocator can
be used for many subsequent allocations. n is passed only to ensure the
minimum necessary for the next allocation. The factory object is allowed to hold
state, which will be stored inside AllocatorList as a direct public member
called factory.

Alias for typeof(Factory()(1)), i.e. the type of the individual
allocators.

BookkeepingAllocator bkalloc;

If BookkeepingAllocator is not NullAllocator, bkalloc is
defined and accessible.

this(ref Factory plant);

this(Factory plant);

Constructs an AllocatorList given a factory object. This constructor is
defined only if Factory has state.

enum uint alignment;

The alignment offered.

void[] allocate(size_t s);

Allocate a block of size s. First tries to allocate from the existing
list of already-created allocators. If neither can satisfy the request,
creates a new allocator by calling make(s) and delegates the request
to it. However, if the allocation fresh off a newly created allocator
fails, subsequent calls to allocate will not cause more calls to make.

Ternary owns(void[] b);

Defined only if Allocator defines owns. Tries each allocator in
turn, in most-recently-used order. If the owner is found, it is moved to
the front of the list as a side effect under the assumption it will be used
soon.

Returns:

Ternary.yes if one allocator was found to return Ternary.yes,
Ternary.no if all component allocators returned Ternary.no, and
Ternary.unknown if no allocator returned Ternary.yes and at least one
returned Ternary.unknown.

bool expand(ref void[] b, size_t delta);

Defined only if Allocator.expand is defined. Finds the owner of b
and calls expand for it. The owner is not brought to the head of the
list.

bool reallocate(ref void[] b, size_t s);

Defined only if Allocator.reallocate is defined. Finds the owner of
b and calls reallocate for it. If that fails, calls the global
reallocate, which allocates a new block and moves memory.

bool deallocate(void[] b);

Defined if Allocator.deallocate and Allocator.owns are defined.

bool deallocateAll();

Defined only if Allocator.owns and Allocator.deallocateAll are
defined.

const pure nothrow @nogc @safe Ternary empty();

Returns Ternary.yes if no allocators are currently active,
Ternary.no otherwise. This methods never returns Ternary.unknown.