std.allocators.allocator

This module contains the definition of the D allocator interface. An allocator is a struct or clas that encapsulates allocating and freeing of blocks of memory. The allocator interface is defined structurally by the isAllocator template. Additionally, a dynamic (runtime) interface that automatically wraps the low-level, non-templated allocator functionality is provided by the DynamicAllocator interface.

Author:
David Simcha

License:
Boost License 1.0.

template isAllocator(A)

Tests whether A conforms to the structural interface of an allocator. An allocator must be a class or struct with member functions/templates and properties with the following signatures and semantics:

// Allocate a raw block of memory of size nBytes.
void* allocate(size_t nBytes);

 // Free a block of memory pointed to by ptr.
void* free(void* ptr);

// Attempt to resize a block of memory pointed to by ptr to size nBytes
// in place.  Return true if successful, false if not.
bool resize(void* ptr, size_t nBytes);

// Whether pointers passed to free() are checked for validity.  Must be
// computable at compile time.
bool freeIsChecked;

// The number of bytes to which an allocation of nBytes is guaranteed to be
// aligned.  Must be static and computable at compile time.
size_t alignBytes(size_t nBytes);

// The amount of space allocated to satisfy a request of size nBytes.
// This may be larger than nBytes due to alignment, etc.  Must be
// computable at compile time.
size_t allocSize(size_t nBytes);

// True if the memory allocated by this allocator is reclaimed automatically
// via garbage collection.  If this is true, free() may be a no-op.
bool isAutomatic;

// True if memory allocated by this allocator is freed when the allocator
// goes out of scope.
bool isScoped;

// Create a new instance of a class on the allocator, passing args to the
// constructor.
T create(T, Args)(auto ref Args args);

// Create a new instance of a struct or primitive on the allocator, passing
// args to the constructor.
T create(T, Args)(auto ref Args args);

// Create a new array of type T with dimensions sizes.  See
// TypedAllocatorMixin for an example.
T newArray(T, I...)(I sizes);

// Same as newArray but do not initialize elements.
T uninitializedArray(T, I...)(I sizes);

// Copy a generic range to an array.
ElementType!(R)[] array(R)(R range);

// Obtain an instance of a DynamicAllocator object that uses this allocator.
// This must be obtained from the allocator instance so that the
// allocator has control over how the DynamicAllocator object is allocated.
@property DynamicAllocator dynamicAllocator();

abstract interface DynamicAllocator;

This interface provides runtime polymorphism for the non-templated portions of the structural interface of allocator. The class DynamicAllocatorTemplate automatically wraps any object conforming to the structural allocator interface in an object inheriting from this runtime polymorphic interface.

Example:

import std.allocators.gcallocator;

auto gcAlloc = GCAllocator();
DynamicAllocator dynamic = gcAlloc.dynamicAllocator;
assert(dynamic.allocate(42));

abstract void* allocate(size_t); abstract void free(void*); abstract bool resize(void*, size_t); abstract @property bool freeIsChecked(); abstract size_t alignBytes(size_t); abstract size_t allocSize(size_t); abstract @property bool isAutomatic(); abstract @property bool isScoped();: Allocator interface as described in isAllocator, excluding templated convenience functions and compile-time computability.

class DynamicAllocatorTemplate(A): DynamicAllocator;

This class wraps any object conforming to the structural allocator interface in a runtime polymorphic object conforming to the DynamicAllocator runtime interface. It should only be used when creating a new allocator type.

Examples:

struct SomeAllocator
{
    @property DynamicAllocator dynamicAllocator()
    {
        return new DynamicAllocatorTemplate!(SomeAllocator)(this);
    }
}

auto this(A baseAlloc);: Construct a DynamicAllocatorTemplate with alloc as its base allocator.

template TypedAllocatorMixin()

This mixin provides default implementations of the high-level templated allocator functions in terms of the low-level non-templated functions. An allocator may use these or may include its own implementations of this functionality.

C create(C, Args...)(auto ref Args args);

Create a new instance of a class on the current allocator, passing args to its constructor.

Examples:

    import std.allocators.region;

    class C {}

    void main()
    {
        auto alloc = newRegionAllocator();
        auto c = alloc.create!C();
    }

T* create(T, Args...)(auto ref Args args);

Create a new instance of a non-class type on the current allocator, passing args to the constructor in the case of a struct or initializing the value to args[0] if args.length == 1 and T is a primitive.

auto newArray(T, I...)(I sizes);

Allocates an array of type T. T may be a multidimensional array. In this case sizes may be specified for any number of dimensions from 1 to the number in T.

Examples:

    import std.allocators.region;

    void main()
    {
        auto alloc = newRegionAllocator();
        double[] arr = alloc.newArray!(double[])(100);
        assert(arr.length == 100);

        double[][] matrix = alloc.newArray!(double[][])(42, 31);
        assert(matrix.length == 42);
        assert(matrix[0].length == 31);
    }

auto uninitializedArray(T, I...)(I sizes);

Same as newArray, except skips initialization of elements for occasions when greater performance is required.

ElementType!(R)[] array(R)(R range);

Copies an input range to an array allocated on the current allocator.

std

etc

core

std.allocators.allocator