Library Reference

version 2.111.0

Internal API

If you spot a problem with this page, click here to create a Bugzilla issue.

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 usinga local clone.

std.experimental.allocator.building_blocks.quantizer

Sourcestd/experimental/allocator/building_blocks/quantizer.d

structQuantizer(ParentAllocator, alias roundingFunction);

This allocator sits on top ofParentAllocator and quantizes allocation sizes,usually from arbitrary positive numbers to a small set of round numbers (e.g.powers of two, page sizes etc). This technique is commonly used to:

Preallocate more memory than requested such that later on, whenreallocation is needed (e.g. to grow an array), expansion can be done quicklyin place. Reallocation to smaller sizes is also fast (in-place) when the newsize requested is within the same quantum as the existing size. Code that'sreallocation-heavy can therefore benefit from fronting a generic allocator withaQuantizer. These advantages are present even ifParentAllocator does notsupport reallocation at all.
Improve behavior of allocators sensitive to allocation sizes, such asFreeList andFreeTree. Rounding allocation requests up makes for smallerfree lists/trees at the cost of slack memory (internal fragmentation).

The following methods are forwarded to the parent allocator if present:allocateAll,owns,deallocateAll,empty.

PreconditionsroundingFunction must satisfy three constraints. These arenot enforced (save for the use ofassert) for the sake of efficiency.

roundingFunction(n) >= n for alln of typesize_t;
roundingFunction must be monotonically increasing, i.e.roundingFunction(n1) <= roundingFunction(n2) for alln1 < n2;
roundingFunction must benothrow,@safe,@nogc andpure, i.e.always return the same value for a givenn.

Examples:

import std.experimental.allocator.building_blocks.free_tree : FreeTree;import std.experimental.allocator.gc_allocator : GCAllocator;size_t roundUpToMultipleOf(size_t s,uint base){auto rem = s % base;return rem ? s + base - rem : s;}// Quantize small allocations to a multiple of cache line, large ones to a// multiple of page sizealias MyAlloc =Quantizer!(    FreeTree!GCAllocator,    n => roundUpToMultipleOf(n, n <= 16_384 ? 64 : 4096));MyAlloc alloc;const buf = alloc.allocate(256);assert(buf.ptr);

ParentAllocatorparent;: The parent allocator. Depending on whetherParentAllocator holds state or not, this is a member variable or an alias forParentAllocator.instance.
size_tgoodAllocSize(size_tn);: ReturnsroundingFunction(n).
enum autoalignment;: Alignment is identical to that of the parent.
void[]allocate(size_tn);: Gets a larger bufferbuf by callingparent.allocate(goodAllocSize(n)). Ifbuf isnull, returnsnull. Otherwise, returnsbuf[0 .. n].
void[]alignedAllocate(size_tn, uinta);: Defined only ifparent.alignedAllocate exists and works similarly toallocate by forwarding toparent.alignedAllocate(goodAllocSize(n), a).
boolexpand(ref void[]b, size_tdelta);: First checks whether there's enough slack memory preallocated forb by evaluatingb.length + delta <= goodAllocSize(b.length). If that's the case, expandsb in place. Otherwise, attempts to useparent.expand appropriately if present.
boolreallocate(ref void[]b, size_ts);: Expands or shrinks allocated block to an allocated size of goodAllocSize(s). Expansion occurs in place under the conditions required byexpand. Shrinking occurs in place ifgoodAllocSize(b.length) == goodAllocSize(s).
boolalignedReallocate(ref void[]b, size_ts, uinta);: Defined only ifParentAllocator.alignedAllocate exists. Expansion occurs in place under the conditions required byexpand. Shrinking occurs in place ifgoodAllocSize(b.length) == goodAllocSize(s).
booldeallocate(void[]b);: Defined ifParentAllocator.deallocate exists and forwards toparent.deallocate(b.ptr[0 .. goodAllocSize(b.length)]).

Movatterモバイル変換

Library Reference

std.experimental.allocator.building_blocks.quantizer