std.experimental.allocator.building_blocks

In addition to defining the interfaces above, this package also implements untyped composable memory allocators. They are untyped because they deal exclusively in void[] and have no notion of what type the memory allocated would be destined for. They are composable because the included allocators are building blocks that can be assembled in complex nontrivial allocators.

Unlike the allocators for the C and C++ programming languages, which manage the allocated size internally, these allocators require that the client maintains (or knows a priori) the allocation size for each piece of memory allocated. Put simply, the client must pass the allocated size upon deallocation. Storing the size in the allocator has significant negative performance implications, and is virtually always redundant because client code needs knowledge of the allocated size in order to avoid buffer overruns. (See more discussion in a proposal for sized deallocation in C++.) For this reason, allocators herein traffic in void[] as opposed to void*.

In order to be usable as an allocator, a type should implement the following methods with their respective semantics. Only alignment and allocate are required. If any of the other methods is missing, the allocator is assumed to not have that capability (for example some allocators do not offer manual deallocation of memory). Allocators should NOT implement unsupported methods to always fail. For example, an allocator that lacks the capability to implement alignedAllocate should not define it at all (as opposed to defining it to always return null or throw an exception). The missing implementation statically informs other components about the allocator's capabilities and allows them to make design decisions accordingly.

Method name	Semantics
uint alignment; Post: result > 0	Returns the minimum alignment of all data returned by the allocator. An allocator may implement alignment as a statically-known enum value only. Applications that need dynamically-chosen alignment values should use the alignedAllocate and alignedReallocate APIs.
size_t goodAllocSize(size_t n); Post: result >= n	Allocators customarily allocate memory in discretely-sized chunks. Therefore, a request for n bytes may result in a larger allocation. The extra memory allocated goes unused and adds to the so-called internal fragmentation. The function goodAllocSize(n) returns the actual number of bytes that would be allocated upon a request for n bytes. This module defines a default implementation that returns n rounded up to a multiple of the allocator's alignment.
void[] allocate(size_t s); Post: result is null || result.length == s	If s == 0, the call may return any empty slice (including null). Otherwise, the call allocates s bytes of memory and returns the allocated block, or null if the request could not be satisfied.
void[] alignedAllocate(size_t s, uint a); Post: result is null || result.length == s	Similar to allocate, with the additional guarantee that the memory returned is aligned to at least a bytes. a must be a power of 2.
void[] allocateAll();	Offers all of allocator's memory to the caller, so it's usually defined by fixed-size allocators. If the allocator is currently NOT managing any memory, then allocateAll() shall allocate and return all memory available to the allocator, and subsequent calls to all allocation primitives should not succeed (e..g allocate shall return null etc). Otherwise, allocateAll only works on a best-effort basis, and the allocator is allowed to return null even if does have available memory. Memory allocated with allocateAll is not otherwise special (e.g. can be reallocated or deallocated with the usual primitives, if defined).
bool expand(ref void[] b, size_t delta); Post: !result || b.length == old(b).length + delta	Expands b by delta bytes. If delta == 0, succeeds without changing b. If b is null, returns false (the null pointer cannot be expanded in place). Otherwise, b must be a buffer previously allocated with the same allocator. If expansion was successful, expand changes b's length to b.length + delta and returns true. Upon failure, the call effects no change upon the allocator object, leaves b unchanged, and returns false.
bool reallocate(ref void[] b, size_t s); Post: !result || b.length == s	Reallocates b to size s, possibly moving memory around. b must be null or a buffer allocated with the same allocator. If reallocation was successful, reallocate changes b appropriately and returns true. Upon failure, the call effects no change upon the allocator object, leaves b unchanged, and returns false. An allocator should implement reallocate if it can derive some advantage from doing so; otherwise, this module defines a reallocate free function implemented in terms of expand, allocate, and deallocate.
bool alignedReallocate(ref void[] b, size_t s, uint a); Post: !result || b.length == s	Similar to reallocate, but guarantees the reallocated memory is aligned at a bytes. The buffer must have been originated with a call to alignedAllocate. a must be a power of 2 greater than (void*).sizeof. An allocator should implement alignedReallocate if it can derive some advantage from doing so; otherwise, this module defines a alignedReallocate free function implemented in terms of expand, alignedAllocate, and deallocate.
Ternary owns(void[] b);	Returns Ternary.yes if b has been allocated with this allocator. An allocator should define this method only if it can decide on ownership precisely and fast (in constant time, logarithmic time, or linear time with a low multiplication factor). Traditional allocators such as the C heap do not define such functionality. If b is null, the allocator shall return Ternary.no, i.e. no allocator owns the null slice.
void[] resolveInternalPointer(void* p);	If p is a pointer somewhere inside a block allocated with this allocator, returns a pointer to the beginning of the allocated block. Otherwise, returns null. If the pointer points immediately after an allocated block, the result is implementation defined.
bool deallocate(void[] b);	If b is null, does nothing and returns true. Otherwise, deallocates memory previously allocated with this allocator and returns true if successful, false otherwise. An implementation that would not support deallocation (i.e. would always return false should not define this primitive at all.)
bool deallocateAll(); Post: empty	Deallocates all memory allocated with this allocator. If an allocator implements this method, it must specify whether its destructor calls it, too.
Ternary empty();	Returns Ternary.yes if and only if the allocator holds no memory (i.e. no allocation has occurred, or all allocations have been deallocated).
static Allocator instance; Post: instance is a valid Allocator object	Some allocators are monostate, i.e. have only an instance and hold only global state. (Notable examples are C's own malloc-based allocator and D's garbage-collected heap.) Such allocators must define a static instance instance that serves as the symbolic placeholder for the global instance of the allocator. An allocator should not hold state and define instance simultaneously. Depending on whether the allocator is thread-safe or not, this instance may be shared.

Sample Assembly

The example below features an allocator modeled after jemalloc, which uses a battery of free-list allocators spaced so as to keep internal fragmentation to a minimum. The FList definitions specify no bounds for the freelist because the Segregator does all size selection in advance. Sizes through 3584 bytes are handled via freelists of staggered sizes. Sizes from 3585 bytes through 4072 KB are handled by a BitmappedBlock with a block size of 4 KB. Sizes above that are passed direct to the Mallocator.

    alias FList = FreeList!(GCAllocator, 0, unbounded);
    alias A = Segregator!(
        8, FreeList!(GCAllocator, 0, 8),
        128, Bucketizer!(FList, 1, 128, 16),
        256, Bucketizer!(FList, 129, 256, 32),
        512, Bucketizer!(FList, 257, 512, 64),
        1024, Bucketizer!(FList, 513, 1024, 128),
        2048, Bucketizer!(FList, 1025, 2048, 256),
        3584, Bucketizer!(FList, 2049, 3584, 512),
        4072 * 1024, AllocatorList!(
            () => BitmappedBlock!(GCAllocator, 4096)(4072 * 1024)),
        GCAllocator
    );
    A tuMalloc;
    auto b = tuMalloc.allocate(500);
    assert(b.length == 500);
    auto c = tuMalloc.allocate(113);
    assert(c.length == 113);
    assert(tuMalloc.expand(c, 14));
    tuMalloc.deallocate(b);
    tuMalloc.deallocate(c);

Allocating memory for sharing across threads

One allocation pattern used in multithreaded applications is to share memory across threads, and to deallocate blocks in a different thread than the one that allocated it. All allocators in this module accept and return void[] (as opposed to shared void[]). This is because at the time of allocation, deallocation, or reallocation, the memory is effectively not shared (if it were, it would reveal a bug at the application level). The issue remains of calling a.deallocate(b) from a different thread than the one that allocated b. It follows that both threads must have access to the same instance a of the respective allocator type. By definition of D, this is possible only if a has the shared qualifier. It follows that the allocator type must implement allocate and deallocate as shared methods. That way, the allocator commits to allowing usable shared instances. Conversely, allocating memory with one non-shared allocator, passing it across threads (by casting the obtained buffer to shared), and later deallocating it in a different thread (either with a different allocator object or with the same allocator object after casting it to shared) is illegal.

Building Blocks

The table below gives a synopsis of predefined allocator building blocks, with their respective modules. Either import the needed modules individually, or import std.experimental.building_blocks, which imports them all publicly. The building blocks can be assembled in unbounded ways and also combined with your own. For a collection of typical and useful preassembled allocators and for inspiration in defining more such assemblies, refer to std.experimental.allocator.showcase.

Allocator	Description
NullAllocator std.experimental.allocator.building_blocks.null_allocator	Very good at doing absolutely nothing. A good starting point for defining other allocators or for studying the API.
GCAllocator std.experimental.allocator.gc_allocator	The system-provided garbage-collector allocator. This should be the default fallback allocator tapping into system memory. It offers manual free and dutifully collects litter.
Mallocator std.experimental.allocator.mallocator	The C heap allocator, a.k.a. malloc/realloc/free. Use sparingly and only for code that is unlikely to leak.
AlignedMallocator std.experimental.allocator.mallocator	Interface to OS-specific allocators that support specifying alignment: posix_memalign on Posix and _aligned_xxx on Windows.
AffixAllocator std.experimental.allocator.building_blocks.affix_allocator	Allocator that allows and manages allocating extra prefix and/or a suffix bytes for each block allocated.
BitmappedBlock std.experimental.allocator.building_blocks.bitmapped_block	Organizes one contiguous chunk of memory in equal-size blocks and tracks allocation status at the cost of one bit per block.
FallbackAllocator std.experimental.allocator.building_blocks.fallback_allocator	Allocator that combines two other allocators - primary and fallback. Allocation requests are first tried with primary, and upon failure are passed to the fallback. Useful for small and fast allocators fronting general-purpose ones.
FreeList std.experimental.allocator.building_blocks.free_list	Allocator that implements a free list on top of any other allocator. The preferred size, tolerance, and maximum elements are configurable at compile- and run time.
SharedFreeList std.experimental.allocator.building_blocks.free_list	Same features as FreeList, but packaged as a shared structure that is accessible to several threads.
FreeTree std.experimental.allocator.building_blocks.free_tree	Allocator similar to FreeList that uses a binary search tree to adaptively store not one, but many free lists.
Region std.experimental.allocator.building_blocks.region	Region allocator organizes a chunk of memory as a simple bump-the-pointer allocator.
InSituRegion std.experimental.allocator.building_blocks.region	Region holding its own allocation, most often on the stack. Has statically-determined size.
SbrkRegion std.experimental.allocator.building_blocks.region	Region using sbrk for allocating memory.
MmapAllocator std.experimental.allocator.mmap_allocator	Allocator using mmap directly.
StatsCollector std.experimental.allocator.building_blocks.stats_collector	Collect statistics about any other allocator.
Quantizer std.experimental.allocator.building_blocks.quantizer	Allocates in coarse-grained quantas, thus improving performance of reallocations by often reallocating in place. The drawback is higher memory consumption because of allocated and unused memory.
AllocatorList std.experimental.allocator.building_blocks.allocator_list	Given an allocator factory, lazily creates as many allocators as needed to satisfy allocation requests. The allocators are stored in a linked list. Requests for allocation are satisfied by searching the list in a linear manner.
Segregator std.experimental.allocator.building_blocks.segregator	Segregates allocation requests by size and dispatches them to distinct allocators.
Bucketizer std.experimental.allocator.building_blocks.bucketizer	Divides allocation sizes in discrete buckets and uses an array of allocators, one per bucket, to satisfy requests.