std.experimental.allocator.building_blocks.kernighan_ritchie

Source: std/experimental/allocator/building_blocks/kernighan_ritchie.d

struct KRRegion

Types 1

structKRRegion(ParentAllocator = NullAllocator)

KRRegion draws inspiration from the region allocation strategy and also the

famed allocator described by Brian Kernighan and Dennis Ritchie in section 8.7

of the book "The C Programming Language", Second Edition, Prentice Hall, 1988.

KRRegion = Region + Kernighan-Ritchie Allocator

Initially, KRRegion starts in "region" mode: allocations are served from the memory chunk in a region fashion. Thus, as long as there is enough memory left, KRRegion.allocate has the performance profile of a region allocator. Deallocation inserts (in 1 time) the deallocated blocks in an unstructured freelist, which is not read in region mode.

Once the region cannot serve an allocate request, KRRegion switches to "free list" mode. It sorts the list of previously deallocated blocks by address and serves allocation requests off that free list. The allocation and deallocation follow the pattern described by Kernighan and Ritchie.

The recommended use of KRRegion is as a region with deallocation. If the KRRegion is dimensioned appropriately, it could often not enter free list mode during its lifetime. Thus it is as fast as a simple region, whilst offering deallocation at a small cost. When the region memory is exhausted, the previously deallocated memory is still usable, at a performance cost. If the region is not excessively large and fragmented, the linear allocation and deallocation cost may still be compensated for by the good locality characteristics.

If the chunk of memory managed is large, it may be desirable to switch management to free list from the beginning. That way, memory may be used in a more compact manner than region mode. To force free list mode, call switchToFreeList shortly after construction or when deemed appropriate.

The smallest size that can be allocated is two words (16 bytes on 64-bit systems, 8 bytes on 32-bit systems). This is because the free list management needs two words (one for the length, the other for the next pointer in the singly-linked list).

The ParentAllocator type parameter is the type of the allocator used to allocate the memory chunk underlying the KRRegion object. Choosing the default (NullAllocator) means the user is responsible for passing a buffer at construction (and for deallocating it if necessary). Otherwise, KRRegion automatically deallocates the buffer during destruction. For that reason, if ParentAllocator is not NullAllocator, then KRRegion is not copyable.

Implementation Details

In free list mode, KRRegion embeds a free blocks list onto the chunk of memory. The free list is circular, coalesced, and sorted by address at all times. Allocations and deallocations take time proportional to the number of previously deallocated blocks. (In practice the cost may be lower, e.g. if memory is deallocated in reverse order of allocation, all operations take constant time.) Memory utilization is good (small control structure and no per-allocation overhead). The disadvantages of freelist mode include proneness to fragmentation, a minimum allocation size of two words, and linear worst-case allocation and deallocation times.

Similarities of KRRegion (in free list mode) with the Kernighan-Ritchie allocator:

  • Free blocks have variable size and are linked in a singly-linked list.
  • The freelist is maintained in increasing address order, which makes

    coalescing easy.

  • The strategy for finding the next available block is first fit.
  • The free list is circular, with the last node pointing back to the first.
  • Coalescing is carried during deallocation.

Differences from the Kernighan-Ritchie allocator:

  • Once the chunk is exhausted, the Kernighan-Ritchie allocator allocates

    another chunk using operating system primitives. For better composability, KRRegion just gets full (returns null on new allocation requests). The decision to allocate more blocks is deferred to a higher-level entity. For an example, see the example below using AllocatorList in conjunction with KRRegion.

  • Allocated blocks do not hold a size prefix. This is because in D the size

    information is available in client code at deallocation time.

Fields
private void[] payload
private Node * root
private size_t bytesUsedRegionMode
Node.alignof alignmentWord-level alignment.
Methods
private bool regionMode() nothrow @nogc @safe const
private void cancelRegionMode() nothrow @nogc @safe
auto byNodePtr()
string toString()
private void assertValid(string s)
private Node * sortFreelist(Node * root) nothrow @nogc @safe
private Node * merge(Node * left, Node * right) nothrow @nogc @safe
private void coalesceAndMakeCircular() nothrow @nogc @safe
void switchToFreeList() nothrow @nogc @safeForces free list mode. If already in free list mode, does nothing. Otherwise, sorts the free list accumulated so far and switches strategy for future allocations to KR style.
void[] allocate(size_t n) nothrow @nogc @safeAllocates `n` bytes. Allocation searches the list of available blocks until a free block with `n` or more bytes is found (first fit strategy). The block is split (if larger) and returned.
bool deallocate(void[] b) nothrow @nogcDeallocates `b`, which is assumed to have been previously allocated with this allocator. Deallocation performs a linear search in the free list to preserve its sorting order. It follows that blocks...
void[] allocateAll() nothrow @nogc @safeAllocates all memory available to this allocator. If the allocator is empty, returns the entire available block of memory. Otherwise, it still performs a best-effort allocation: if there is no frag...
bool deallocateAll() pure nothrow @nogcDeallocates all memory currently allocated, making the allocator ready for other allocations. This is a 1 operation.
Ternary owns(void[] b) pure nothrow @trusted @nogcChecks whether the allocator is responsible for the allocation of `b`. It does a simple 1 range check. `b` should be a buffer either allocated with `this` or obtained through other means.
size_t goodAllocSize(size_t n) pure nothrow @safe @nogcAdjusts `n` to a size suitable for allocation (two words or larger, word-aligned).
Ternary empty() pure nothrow @safe @nogcReturns: `Ternary.yes` if the allocator is empty, `Ternary.no` otherwise. Never returns `Ternary.unknown`.
Constructors
this(ubyte[] b)Create a `KRRegion`. If `ParentAllocator` is not `NullAllocator`, `KRRegion`'s destructor will call `parent.deallocate`.
Nested Templates
Node