Menu
Search

API Documentation

version 2.096.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.Region

A Region allocator allocates memory straight from one contiguous chunk. There is no deallocation, and once the region is full, allocation requests return null. Therefore, Regions are often used (a) in conjunction with more sophisticated allocators; or (b) for batch-style very fast allocations that deallocate everything at once.

struct Region(ParentAllocator, uint minAlign = platformAlignment, Flag!("growDownwards") growDownwards = No.growDownwards) ;

The region only stores three pointers, corresponding to the current position in the store and the limits. One allocation entails rounding up the allocation size for alignment purposes, bumping the current pointer, and comparing it against the limit.

If ParentAllocator is different from NullAllocator, Region deallocates the chunk of memory during destruction.

The minAlign parameter establishes alignment. If minAlign > 1, the sizes of all allocation requests are rounded up to a multiple of minAlign. Applications aiming at maximum speed may want to choose minAlign = 1 and control alignment externally.

Constructors

NameDescription
this (store) Constructs a region backed by a user-provided store. Assumes the memory was allocated with ParentAllocator (if different from NullAllocator).

Fields

NameTypeDescription
parent ParentAllocatorThe parent allocator. Depending on whether ParentAllocator holds state or not, this is a member variable or an alias for ParentAllocator.instance.

Methods

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

Aliases

NameDescription
alignment Alignment offered.

Example

import std.algorithm.comparison : max;
import std.experimental.allocator.building_blocks.allocator_list
    : AllocatorList;
import std.experimental.allocator.mallocator : Mallocator;
import std.typecons : Ternary;
// Create a scalable list of regions. Each gets at least 1MB at a time by
// using malloc.
auto batchAllocator = AllocatorList!(
    (size_t n) => Region!Mallocator(max(n, 1024 * 1024))
)();
writeln(batchAllocator.empty); // Ternary.yes
auto b = batchAllocator.allocate(101);
writeln(b.length); // 101
writeln(batchAllocator.empty); // Ternary.no
// This will cause a second allocation
b = batchAllocator.allocate(2 * 1024 * 1024);
writeln(b.length); // 2 * 1024 * 1024
// Destructor will free the memory

Authors

License