ae.utils.alloc

Composable allocators

This module uses a composing system - allocators implementing various strategies allocate memory in bulk from another backend allocator, "chained" in as a template alias or string parameter.

Various allocation strategies allow for various capabilities - e.g. some strategies may not keep metadata required to free the memory of individual instances. Code should test the presence of primitives (methods in allocator mixin instances) accordingly.

Most allocators have two parts: data and implementation. The split is done to allow all implementation layers to share the same "this" pointer. Each "Impl" part takes its "data" part as an alias.

The underlying allocator (or its implementation instantiation) is passed in as an alias template parameter. This means that it has to be a symbol, the address of which is known in the scope of the allocator - thus, something scoped in the same class/struct, or a global variable.

Allocator kinds:

* Homogenous allocators, once instantiated, can only allocate values only of the type specified in the template parameter. Attempting to allocate a different type will result in a compile-time error.

* Heterogenous allocators are not bound by one type. One instance can allocate values of multiple types.

Allocator primitives:

allocate Return a pointer to a new instance. The returned object is not initialized. The only mandatory primitive.

create Allocate and initialize/construct a new instance of T, with the supplied parameters.

free Free memory at the given pointer, assuming it was allocated by the same allocator.

destroy Finalize and free the given pointer.

allocateMany Allocate an array of values, with the given size. Allocators which support this primitive are referred to as "bulk allocators".

freeMany Free memory for the given array of values.

resize Resize an array of values. Reallocate if needed.

freeAll Free all memory allocated using the given allocator, at once. Deallocates storage from underlying allocator, if applicable.

clear Mark all memory allocated by the top-layer allocator as free. Does not deallocate memory from underlying allocator.

References: http://accu.org/content/conf2008/Alexandrescu-memory-allocation.screen.pdf

Members

Classes

BufferExhaustedException
class BufferExhaustedException

Thrown when the buffer of an allocator is exhausted.

Functions

allocate
RefType!T allocate(A a)
Undocumented in source. Be warned that the author may not have intended to support it.
create
RefType!T create(A a, Args args)

Default "create" implementation.

destroy
void destroy(A a, R r)
Undocumented in source. Be warned that the author may not have intended to support it.
free
void free(A a, R r)
Undocumented in source. Be warned that the author may not have intended to support it.

Mixin templates

AllocTypes
mixintemplate AllocTypes()

Creates T/R/V aliases from context, and checks ALLOCATOR_TYPE if appropriate.

AllocatorCommon
mixintemplate AllocatorCommon()

Common declarations for an allocator mixin

PointerBumpCommon
mixintemplate PointerBumpCommon()

Common code for pointer-bumping allocator implementations.

Structs

BufferAllocator
struct BufferAllocator(BASE_TYPE = ubyte)

Homogenous allocator which uses a given buffer. Throws BufferExhaustedException if the buffer is exhausted.

DataAllocator
struct DataAllocator

Backend allocator using the Data type from ae.sys.data.

FreeListAllocator
struct FreeListAllocator(ALLOCATOR_TYPE, alias ALLOCATOR = heapAllocator)

Homogenous linked list allocator. Supports O(1) deletion. Does not support bulk allocation.

GCRootAllocatorProxy
struct GCRootAllocatorProxy(alias ALLOCATOR)
Undocumented in source.
GrowingBufferAllocator
struct GrowingBufferAllocator(BASE_TYPE = void*, alias ALLOCATOR = heapAllocator)

Growing buffer bulk allocator. Allows reusing the same buffer, which is grown and retained as needed. Requires .resize support from underlying allocator. Smaller buffers are discarded (neither freed nor reused).

HeapAllocator
struct HeapAllocator

Backend allocator Allocates from D's managed heap directly.

HybridBufferAllocator
struct HybridBufferAllocator(size_t SIZE, BASE_TYPE = ubyte, alias ALLOCATOR = heapAllocator)

A bulk allocator which behaves like a StaticBufferAllocator initially, but once the static buffer is exhausted, it switches to a fallback bulk allocator. Needs to be manually initialized before use. ALLOCATOR is the fallback allocator.

InitializingAllocatorProxy
struct InitializingAllocatorProxy(string INIT_CODE, alias ALLOCATOR = heapAllocator)

Allocator proxy which injects custom code after object creation. Context of INIT_CODE: p - newly-allocated value.

PageAllocator
struct PageAllocator

Backend for direct OS page allocation.

RegionAllocator
struct RegionAllocator(BASE_TYPE = void*, size_t BLOCKSIZE = 1024, alias ALLOCATOR = heapAllocator)

Classic region. Compose over another allocator to allocate values in bulk (minimum of BLOCKSIZE). No deletion, but is slightly faster that FreeListAllocator. BASE_TYPE indicates the type used for upstream allocations. It is not possible to bulk-allocate types smaller than BASE_TYPE, or those the size of which is not divisible by BASE_TYPE's size. (This restriction allows for allocations of single BASE_TYPE-sized items to be a little faster.)

StatAllocatorProxy
struct StatAllocatorProxy(alias ALLOCATOR = heapAllocator)

Allocator proxy which keeps track how many allocations were made.

StaticBufferAllocator
struct StaticBufferAllocator(size_t SIZE, BASE_TYPE = ubyte)

Homogenous allocator which uses a static buffer of a given size. Throws BufferExhaustedException if the buffer is exhausted. Needs to be manually initialized before use.

TrackingAllocatorProxy
struct TrackingAllocatorProxy(ALLOCATOR_TYPE, alias ALLOCATOR = heapAllocator)

Allocator proxy which keeps track of all allocations, and implements freeAll by discarding them all at once via the underlying allocator's freeMany.

WrapParts
struct WrapParts(T)

Instantiates a struct from a type containing a Data/Impl template pair.

Templates

FreeListNode
template FreeListNode(T)

The internal unit allocation type of FreeListAllocator. (Exposed to allow specializing underlying allocators on it.)

PartsWrapper
template PartsWrapper(alias T)

Creates a template which, when instantiated, forwards its arguments to T and uses WrapParts on the result.

mixAliasForward
template mixAliasForward(alias M, string name = __traits(identifier, M))

Generates code to create forwarding aliases to the given mixin/template member. Used as a replacement for "alias M this", which doesn't seem to work with mixins and templates.

Variables

heapAllocator
HeapAllocator heapAllocator;
Undocumented in source.

Meta

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Authors

Vladimir Panteleev <vladimir@thecybershadow.net>