InSituRegion

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

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.

struct InSituRegion (
size_t size
size_t minAlign = platformAlignment
) {
version(X86)
enum growDownwards;
version(!X86 && X86_64)
enum growDownwards;
version(!X86 && !X86_64 && ARM)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && AArch64)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && !AArch64 && PPC)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && !AArch64 && !PPC && PPC64)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && !AArch64 && !PPC && !PPC64 && MIPS32)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && !AArch64 && !PPC && !PPC64 && !MIPS32 && MIPS64)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && !AArch64 && !PPC && !PPC64 && !MIPS32 && !MIPS64 && SPARC)
enum growDownwards;
version(!X86 && !X86_64 && !ARM && !AArch64 && !PPC && !PPC64 && !MIPS32 && !MIPS64 && !SPARC && SystemZ)
enum growDownwards;
}

Postblit

A postblit is present on this object, but not explicitly documented in the source.

Members

Aliases

alignment
alias alignment = minAlign

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.

Functions

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

As above, but the memory allocated is aligned at a bytes.

allocate
void[] allocate(size_t 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
void[] allocateAll()

Allocates all memory available with this allocator.

available
size_t available()

Nonstandard function that returns the bytes available for allocation.

deallocate
bool deallocate(void[] 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
bool deallocateAll()

Deallocates all memory allocated with this allocator.

expand
bool expand(void[] b, size_t delta)

Expands an allocated block in place. Expansion will succeed only if the block is the last allocated.

owns
Ternary owns(void[] b)

Returns Ternary.yes if b is the result of a previous allocation, Ternary.no otherwise.

Examples

1 // 128KB region, allocated to x86's cache line
2 InSituRegion!(128 * 1024, 16) r1;
3 auto a1 = r1.allocate(101);
4 assert(a1.length == 101);
5 
6 // 128KB region, with fallback to the garbage collector.
7 import std.experimental.allocator.building_blocks.fallback_allocator
8 : FallbackAllocator;
9 import std.experimental.allocator.building_blocks.free_list
10 : FreeList;
11 import std.experimental.allocator.building_blocks.bitmapped_block
12 : BitmappedBlock;
13 import std.experimental.allocator.gc_allocator : GCAllocator;
14 FallbackAllocator!(InSituRegion!(128 * 1024), GCAllocator) r2;
15 const a2 = r2.allocate(102);
16 assert(a2.length == 102);
17 
18 // Reap with GC fallback.
19 InSituRegion!(128 * 1024, 8) tmp3;
20 FallbackAllocator!(BitmappedBlock!(64, 8), GCAllocator) r3;
21 r3.primary = BitmappedBlock!(64, 8)(cast(ubyte[]) (tmp3.allocateAll()));
22 const a3 = r3.allocate(103);
23 assert(a3.length == 103);
24 
25 // Reap/GC with a freelist for small objects up to 16 bytes.
26 InSituRegion!(128 * 1024, 64) tmp4;
27 FreeList!(FallbackAllocator!(BitmappedBlock!(64, 64), GCAllocator), 0, 16) r4;
28 r4.parent.primary = BitmappedBlock!(64, 64)(cast(ubyte[]) (tmp4.allocateAll()));
29 const a4 = r4.allocate(104);
30 assert(a4.length == 104);

Meta