View source code
Display the source code in std/experimental/allocator/building_blocks/allocator_list.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
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 local clone.

Struct std.experimental.allocator.building_blocks.allocator_list.AllocatorList

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.

struct AllocatorList(Factory, BookkeepingAllocator) ;
alias AllocatorList(alias factoryFunction, BookkeepingAllocator) = AllocatorList!(Factory,BookkeepingAllocator);

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.

Struct AllocatorList

Constructors

NameDescription
this (plant) Constructs an AllocatorList given a factory object. This constructor is defined only if Factory has state.

Fields

NameTypeDescription
bkalloc BookkeepingAllocatorIf BookkeepingAllocator is not NullAllocator, bkalloc is defined and accessible.

Methods

NameDescription
alignedAllocate (s, theAlignment) Allocate a block of size s with alignment a. 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 + a - 1) and delegates the request to it. However, if the allocation fresh off a newly created allocator fails, subsequent calls to alignedAllocate will not cause more calls to make.
allocate (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.
deallocate (b) Defined if Allocator.deallocate and Allocator.owns are defined.
deallocateAll () Defined only if Allocator.owns and Allocator.deallocateAll are defined.
empty () Returns Ternary.yes if no allocators are currently active, Ternary.no otherwise. This methods never returns Ternary.unknown.
expand (b, 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.
owns (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.
reallocate (b, 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.

Aliases

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

Alias AllocatorList

Parameters

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

Example

import std.algorithm.comparison : max;
import std.experimental.allocator.building_blocks.free_list : ContiguousFreeList;
import std.experimental.allocator.building_blocks.null_allocator : NullAllocator;
import std.experimental.allocator.building_blocks.region : Region;
import std.experimental.allocator.building_blocks.segregator : Segregator;
import std.experimental.allocator.gc_allocator : GCAllocator;
import std.experimental.allocator.mmap_allocator : MmapAllocator;

// Ouroboros allocator list based upon 4MB regions, fetched directly from
// mmap. All memory is released upon destruction.
alias A1 = AllocatorList!((n) => Region!MmapAllocator(max(n, 1024 * 4096)),
    NullAllocator);

// Allocator list based upon 4MB regions, fetched from the garbage
// collector. All memory is released upon destruction.
alias A2 = AllocatorList!((n) => Region!GCAllocator(max(n, 1024 * 4096)));

// Ouroboros allocator list based upon 4MB regions, fetched from the garbage
// collector. Memory is left to the collector.
alias A3 = AllocatorList!(
    (n) => Region!NullAllocator(new ubyte[max(n, 1024 * 4096)]),
    NullAllocator);

// Allocator list that creates one freelist for all objects
alias A4 =
    Segregator!(
        64, AllocatorList!(
            (n) => ContiguousFreeList!(NullAllocator, 0, 64)(
                cast(ubyte[])(GCAllocator.instance.allocate(4096)))),
        GCAllocator);

A4 a;
auto small = a.allocate(64);
assert(small);
a.deallocate(small);
auto b1 = a.allocate(1024 * 8192);
assert(b1 !is null); // still works due to overdimensioning
b1 = a.allocate(1024 * 10);
writeln(b1.length); // 1024 * 10

Authors

License