Menu
Search

API Documentation

version 2.108.0

overview

View source code
Display the source code in std/experimental/allocator/building_blocks/region.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
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 local clone.

Struct std.experimental.allocator.building_blocks.region.InSituRegion

InSituRegion is a convenient region that carries its storage within itself (in the form of a statically-sized array).

struct InSituRegion(ulong size, ulong minAlign = platformAlignment) ;

The first template argument is the size of the region and the second is the needed alignment. Depending on the alignment requested and platform details, the actual available storage may be smaller than the compile-time parameter. To make sure that at least n bytes are available in the region, use InSituRegion!(n + a - 1, a).

Given that the most frequent use of InSituRegion is as a stack allocator, it allocates starting at the end on systems where stack grows downwards, such that hot memory is used first.

Methods

NameDescription
alignedAllocate (n, a) As above, but the memory allocated is aligned at a bytes.
allocate (n) Allocates bytes and returns them, or null if the region cannot accommodate the request. For efficiency reasons, if bytes == 0 the function returns an empty non-null slice.
allocateAll () Allocates all memory available with this allocator.
available () Nonstandard function that returns the bytes available for allocation.
deallocate (b) Deallocates b. This works only if b was obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing. This semantics is tricky and therefore deallocate is defined only if Region is instantiated with Yes.defineDeallocate as the third template argument.
deallocateAll () Deallocates all memory allocated with this allocator.
expand (b, delta) Expands an allocated block in place. Expansion will succeed only if the block is the last allocated.
owns (b) Returns Ternary.yes if b is the result of a previous allocation, Ternary.no otherwise.

Aliases

NameDescription
alignment An alias for minAlign, which must be a valid alignment (nonzero power of 2). The start of the region and all allocation requests will be rounded up to a multiple of the alignment.

Example

// 128KB region, allocated to x86's cache line
InSituRegion!(128 * 1024, 16) r1;
auto a1 = r1.allocate(101);
writeln(a1.length); // 101

// 128KB region, with fallback to the garbage collector.
import std.experimental.allocator.building_blocks.fallback_allocator
    : FallbackAllocator;
import std.experimental.allocator.building_blocks.free_list
    : FreeList;
import std.experimental.allocator.building_blocks.bitmapped_block
    : BitmappedBlock;
import std.experimental.allocator.gc_allocator : GCAllocator;
FallbackAllocator!(InSituRegion!(128 * 1024), GCAllocator) r2;
const a2 = r2.allocate(102);
writeln(a2.length); // 102

// Reap with GC fallback.
InSituRegion!(128 * 1024, 8) tmp3;
FallbackAllocator!(BitmappedBlock!(64, 8), GCAllocator) r3;
r3.primary = BitmappedBlock!(64, 8)(cast(ubyte[]) (tmp3.allocateAll()));
const a3 = r3.allocate(103);
writeln(a3.length); // 103

// Reap/GC with a freelist for small objects up to 16 bytes.
InSituRegion!(128 * 1024, 64) tmp4;
FreeList!(FallbackAllocator!(BitmappedBlock!(64, 64), GCAllocator), 0, 16) r4;
r4.parent.primary = BitmappedBlock!(64, 64)(cast(ubyte[]) (tmp4.allocateAll()));
const a4 = r4.allocate(104);
writeln(a4.length); // 104

Authors

License