BorrowedRegion

A BorrowedRegion allocates directly from a user-provided block of memory.

Unlike a Region, a BorrowedRegion does not own the memory it allocates from and will not deallocate that memory upon destruction. Instead, it is the user's responsibility to ensure that the memory is properly disposed of.

In all other respects, a BorrowedRegion behaves exactly like a Region.

struct BorrowedRegion (

uint minAlign = platformAlignment

Flag!"growDownwards" growDownwards = No.growDownwards

) {

struct Ternary via import std.typecons : Ternary;;

this(ubyte[] store);

size_t goodAllocSize(size_t n);

alias alignment = minAlign;

void[] allocate(size_t n);

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

void[] allocateAll();

static if(growDownwards == No.growDownwards)

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

bool deallocate(void[] b);

bool deallocateAll();

Ternary owns(void[] b);

Ternary empty();

size_t available();

}

Constructors

this this(ubyte[] store): Constructs a region backed by a user-provided store.

Members

Aliases

alignment alias alignment = minAlign: Alignment offered.

Functions

alignedAllocate void[] alignedAllocate(size_t n, uint a): Allocates n bytes of memory aligned at alignment a.
allocate void[] allocate(size_t n): Allocates n bytes of memory. The shortest path involves an alignment adjustment (if alignment > 1), an increment, and a comparison.
allocateAll void[] allocateAll(): Allocates and returns all memory available to this region.
available size_t available(): Nonstandard property that returns 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.
deallocateAll bool deallocateAll(): Deallocates all memory allocated by this region, which can be subsequently reused for new allocations.
empty Ternary empty(): Returns Ternary.yes if no memory has been allocated in this region, Ternary.no otherwise. (Never returns Ternary.unknown.)
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. Defined only if growDownwards is No.growDownwards.
goodAllocSize size_t goodAllocSize(size_t n): Rounds the given size to a multiple of the alignment
owns Ternary owns(void[] b): Queries whether b has been allocated with this region.

Examples

import std.typecons : Ternary;

ubyte[1024] store;
auto myRegion = BorrowedRegion!(1)(store[]);

assert(myRegion.empty == Ternary.yes);
assert(myRegion.available == store.length);

void[] b = myRegion.allocate(101);

assert(b.length == 101);
assert(myRegion.empty == Ternary.no);
assert(myRegion.owns(b) == Ternary.yes);
assert(myRegion.available == store.length - b.length);

void[] b2 = myRegion.allocate(256);

// Can only free the most recent allocation
assert(myRegion.deallocate(b) == false);
assert(myRegion.deallocate(b2) == true);

myRegion.deallocateAll();

assert(myRegion.empty == Ternary.yes);