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.

ae.utils.alloc

Members

Classes

Functions

Mixin templates

Structs

Templates

Variables

Meta

Source

License

Authors