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

High-level interface for allocators. Implements bundled allocation/creation
and destruction/deallocation of data including structs and classes,
and also array primitives related to allocation. This module is the entry point
for both making use of allocators and for their documentation.

Layered Structure

D's allocators have a layered structure in both implementation and documentation:

A high-level, dynamically-typed layer (described further down in this
module). It consists of an interface called IAllocator, which concret;
allocators need to implement. The interface primitives themselves are oblivious
to the type of the objects being allocated; they only deal in void[], by
necessity of the interface being dynamic (as opposed to type-parameterized).
Each thread has a current allocator it uses by default, which is a thread-local
variable theAllocator of type IAllocator. The process has a
global allocator called processAllocator, also of type IAllocator. When a new thread is created, processAllocator is copied
into theAllocator. An application can change the objects to which these
references point. By default, at application startup, processAllocator
refers to an object that uses D's garbage collected heap. This layer also
include high-level functions such as make and dispose that
comfortably allocate/create and respectively destroy/deallocate objects. This
layer is all needed for most casual uses of allocation primitives.

A mid-level, statically-typed layer for assembling several allocators into
one. It uses properties of the type of the objects being created to route
allocation requests to possibly specialized allocators. This layer is relatively
thin and implemented and documented in the std.experimental.allocator.typed module. It allows an interested user to e.g.
use different allocators for arrays versus fixed-sized objects, to the end of
better overall performance.

A low-level collection of highly generic heap building blocks —
Lego-like pieces that can be used to assemble application-specific allocators.
The real allocation smarts are occurring at this level. This layer is of
interest to advanced applications that want to configure their own allocators.
A good illustration of typical uses of these building blocks is module std.experimental.allocator.showcase which defines a collection of frequently-
used preassembled allocator objects. The implementation and documentation entry
point is std.experimental.allocator.building_blocks. By design, the
primitives of the static interface have the same signatures as the IAllocator primitives but are for the most part optional and driven by static
introspection. The parameterized class CAllocatorImpl offers an
immediate and useful means to package a static low-level allocator into an
implementation of IAllocator.

Idiomatic Use of std.experimental.allocator

As of this time, std.experimental.allocator is not integrated with D's
built-in operators that allocate memory, such as new, array literals, or
array concatenation operators. That means std.experimental.allocator is
opt-in — applications need to make explicit use of it.

For casual creation and disposal of dynamically-allocated objects, use make, dispose, and the array-specific functions makeArray,
expandArray, and shrinkArray. These use by default D's garbage
collected heap, but open the application to better configuration options. These
primitives work either with theAllocator but also with any allocator obtained
by combining heap building blocks. For example:

To experiment with alternative allocators, set theAllocator for the
current thread. For example, consider an application that allocates many 8-byte
objects. These are not well supported by the default allocator, so a
free list allocator would be recommended.
To install one in main, the application would use:

Saving the IAllocator Reference For Later Use

As with any global resource, setting theAllocator and processAllocator
should not be done often and casually. In particular, allocating memory with
one allocator and deallocating with another causes undefined behavior.
Typically, these variables are set during application initialization phase and
last through the application.

To avoid this, long-lived objects that need to perform allocations,
reallocations, and deallocations relatively often may want to store a reference
to the allocator object they use throughout their lifetime. Then, instead of
using theAllocator for internal allocation-related tasks, they'd use the
internally held reference. For example, consider a user-defined hash table:

Following initialization, the HashTable object would consistently use its
allocator object for acquiring memory. Furthermore, setting
HashTable.allocator to point to a different allocator should be legal but
only if the object is empty; otherwise, the object wouldn't be able to
deallocate its existing state.

Using Allocators without IAllocator

Allocators assembled from the heap building blocks don't need to go through
IAllocator to be usable. They have the same primitives as IAllocator and
they work with make, makeArray, dispose etc. So it
suffice to create allocator objects wherever fit and use them appropriately:

In this case, myAllocator does not obey the IAllocator interface, but
implements its primitives so it can work with makeArray by means of duck
typing.

One important thing to note about this setup is that statically-typed assembled
allocators are almost always faster than allocators that go through
IAllocator. An important rule of thumb is: "assemble allocator first, adapt
to IAllocator after". A good allocator implements intricate logic by means of
template assembly, and gets wrapped with IAllocator (usually by means of
allocatorObject) only once, at client level.

Dynamic allocator interface. Code that defines allocators ultimately implements
this interface. This should be used wherever a uniform type is required for
encapsulating various allocator implementations.

Composition of allocators is not recommended at this level due to
inflexibility of dynamic interfaces and inefficiencies caused by cascaded
multiple calls. Instead, compose allocators using the static interface defined
in std.experimental.allocator.building_blocks, then adapt the composed
allocator to IAllocator (possibly by using CAllocatorImpl below).

Methods returning Ternary return Ternary.yes upon success,
Ternary.no upon failure, and Ternary.unknown if the primitive is not
implemented by the allocator instance.

abstract @property uint alignment();

Returns the alignment offered.

abstract size_t goodAllocSize(size_t s);

Returns the good allocation size that guarantees zero internal
fragmentation.

abstract void[] allocate(size_t, TypeInfo ti = null);

Allocates n bytes of memory.

abstract void[] alignedAllocate(size_t n, uint a);

Allocates n bytes of memory with specified alignment a. Implementations
that do not support this primitive should always return null.

abstract void[] allocateAll();

Allocates and returns all memory available to this allocator.
Implementations that do not support this primitive should always return
null.

abstract bool expand(ref void[], size_t);

Expands a memory block in place and returns true if successful.
Implementations that don't support this primitive should always return
false.

Returns Ternary.yes if the allocator ownsb, Ternary.no if
the allocator doesn't own b, and Ternary.unknown if ownership
cannot be determined. Implementations that don't support this primitive
should always return Ternary.unknown.

Resolves an internal pointer to the full block allocated. Implementations
that don't support this primitive should always return Ternary.unknown.

abstract bool deallocate(void[] b);

Deallocates a memory block. Implementations that don't support this
primitive should always return false. A simple way to check that an
allocator supports deallocation is to call deallocate(null).

abstract bool deallocateAll();

Deallocates all memory. Implementations that don't support this primitive
should always return false.

abstract Ternary empty();

Returns Ternary.yes if no memory is currently allocated from this
allocator, Ternary.no if some allocations are currently active, or
Ternary.unknown if not supported.

interface ISharedAllocator;

Dynamic shared allocator interface. Code that defines allocators shareable
across threads ultimately implements this interface. This should be used
wherever a uniform type is required for encapsulating various allocator
implementations.

Composition of allocators is not recommended at this level due to
inflexibility of dynamic interfaces and inefficiencies caused by cascaded
multiple calls. Instead, compose allocators using the static interface defined
in std.experimental.allocator.building_blocks, then adapt the composed
allocator to ISharedAllocator (possibly by using CSharedAllocatorImpl below).

Methods returning Ternary return Ternary.yes upon success,
Ternary.no upon failure, and Ternary.unknown if the primitive is not
implemented by the allocator instance.

abstract shared @property uint alignment();

Returns the alignment offered.

abstract shared size_t goodAllocSize(size_t s);

Returns the good allocation size that guarantees zero internal
fragmentation.

abstract shared void[] allocate(size_t, TypeInfo ti = null);

Allocates n bytes of memory.

abstract shared void[] alignedAllocate(size_t n, uint a);

Allocates n bytes of memory with specified alignment a. Implementations
that do not support this primitive should always return null.

abstract shared void[] allocateAll();

Allocates and returns all memory available to this allocator.
Implementations that do not support this primitive should always return
null.

abstract shared bool expand(ref void[], size_t);

Expands a memory block in place and returns true if successful.
Implementations that don't support this primitive should always return
false.

Returns Ternary.yes if the allocator ownsb, Ternary.no if
the allocator doesn't own b, and Ternary.unknown if ownership
cannot be determined. Implementations that don't support this primitive
should always return Ternary.unknown.

Resolves an internal pointer to the full block allocated. Implementations
that don't support this primitive should always return Ternary.unknown.

abstract shared bool deallocate(void[] b);

Deallocates a memory block. Implementations that don't support this
primitive should always return false. A simple way to check that an
allocator supports deallocation is to call deallocate(null).

abstract shared bool deallocateAll();

Deallocates all memory. Implementations that don't support this primitive
should always return false.

abstract shared Ternary empty();

Returns Ternary.yes if no memory is currently allocated from this
allocator, Ternary.no if some allocations are currently active, or
Ternary.unknown if not supported.

nothrow @nogc @property @safe IAllocator theAllocator();

nothrow @nogc @property @safe void theAllocator(IAllocator a);

Gets/sets the allocator for the current thread. This is the default allocator
that should be used for allocating thread-local memory. For allocating memory
to be shared across threads, use processAllocator (below). By default,
theAllocator ultimately fetches memory from processAllocator, which
in turn uses the garbage collected heap.

Dynamically allocates (using alloc) and then creates in the memory
allocated an object of type T, using args (if any) for its
initialization. Initialization occurs in the memory allocated and is otherwise
semantically the same as T(args).
(Note that using alloc.make!(T[]) creates a pointer to an (empty) array
of Ts, not an array. To use an allocator to allocate and initialize an
array, use alloc.makeArray!T described below.)

Parameters:

T

Type of the object being created.

Allocator alloc

The allocator used for getting the needed memory. It may be an object
implementing the static interface for allocators, or an IAllocator
reference.

A args

Optional arguments used for initializing the created object. If not
present, the object is default constructed.

Returns:

If T is a class type, returns a reference to the created T
object. Otherwise, returns a T* pointing to the created object. In all
cases, returns null if allocation failed.

Throws:

If T's constructor throws, deallocates the allocated memory and
propagates the exception.

Grows array by appending delta more elements. The needed memory is
allocated using alloc. The extra elements added are either default-
initialized, filled with copies of init, or initialized with values
fetched from range.

Parameters:

T

element type of the array being created

Allocator alloc

the allocator used for getting memory

T[] array

a reference to the array being grown

size_t delta

number of elements to add (upon success the new length of array is
array.length + delta)

T init

element used for filling the array

R range

range used for initializing the array elements

Returns:

true upon success, false if memory could not be allocated. In the
latter case array is left unaffected.

Throws:

The first two overloads throw only if alloc's primitives do. The
overloads that involve copy initialization deallocate memory and propagate the
exception if the copy operation throws.

If array.length < delta, does nothing and returns false. Otherwise,
destroys the last array.length - delta elements in the array and then
reallocates the array's buffer. If reallocation fails, fills the array with
default-initialized data.

Parameters:

T

element type of the array being created

Allocator alloc

the allocator used for getting memory

T[] array

a reference to the array being shrunk

size_t delta

number of elements to remove (upon success the new length of array is array.length - delta)

Returns:

true upon success, false if memory could not be reallocated. In the latter
case, the slice array[$ - delta .. $] is left with default-initialized
elements.

Throws:

The first two overloads throw only if alloc's primitives do. The
overloads that involve copy initialization deallocate memory and propagate the
exception if the copy operation throws.

Destroys and then deallocates (using alloc) the object pointed to by a
pointer, the class object referred to by a class or interface
reference, or an entire array. It is assumed the respective entities had been
allocated with the same allocator.

Returns a dynamically-typed CAllocator built around a given statically-
typed allocator a of type A. Passing a pointer to the allocator
creates a dynamic allocator around the allocator pointed to by the pointer,
without attempting to copy or move it. Passing the allocator by value or
reference behaves as follows.

If A has no state, the resulting object is allocated in static
shared storage.

If A has state and is copyable, the result will store a copy of it
within. The result itself is allocated in its own statically-typed allocator.

If A has state and is not copyable, the result will move the
passed-in argument into the result. The result itself is allocated in its own
statically-typed allocator.

Returns a dynamically-typed CSharedAllocator built around a given statically-
typed allocator a of type A. Passing a pointer to the allocator
creates a dynamic allocator around the allocator pointed to by the pointer,
without attempting to copy or move it. Passing the allocator by value or
reference behaves as follows.

If A has no state, the resulting object is allocated in static
shared storage.

If A has state and is copyable, the result will store a copy of it
within. The result itself is allocated in its own statically-typed allocator.

If A has state and is not copyable, the result will move the
passed-in argument into the result. The result itself is allocated in its own
statically-typed allocator.