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
			a local clone.
		
	std.experimental.allocator.building_blocks.region
- structRegion(ParentAllocator, uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards);
- ARegionallocator 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.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.Regiondeallocates 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.Examples: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 - ParentAllocatorparent;
- The parent allocator. Depending on whether ParentAllocator holds state or not, this is a member variable or an alias for ParentAllocator.instance.
- pure nothrow @nogc this(ubyte[]store);
 this(size_tn);
 this(ParentAllocatorparent, size_tn);
- Constructs a region backed by a user-provided store. Assumes the memory was allocated with ParentAllocator.Parameters:ubyte[] storeUser-provided store backing up the region. Assumed to have been allocated with ParentAllocator. size_t nBytes to allocate using ParentAllocator. If parent.allocate(n) returns null, the region will be initialized as empty (correctly initialized but unable to allocate).
- pure nothrow @nogc @safe size_tgoodAllocSize(size_tn) const;
- Rounds the given size to a multiple of the alignment
- aliasalignment= minAlign;
- Alignment offered.
- pure nothrow @nogc @trusted void[]allocate(size_tn);
- Allocatesnbytes of memory. The shortest path involves an alignment adjustment (if alignment > 1), an increment, and a comparison.Parameters:size_t nnumber of bytes to allocate Returns:A properly-aligned buffer of sizenor null if request could not be satisfied.
- pure nothrow @nogc @trusted void[]alignedAllocate(size_tn, uinta);
- Allocatesnbytes of memory aligned at alignmenta.Parameters:size_t nnumber of bytes to allocate uint aalignment for the allocated block Returns:Either a suitable block ofnbytes aligned ata, or null.
- pure nothrow @nogc @trusted void[]allocateAll();
- Allocates and returns all memory available to this region.
- pure nothrow @nogc @safe boolexpand(ref void[]b, size_tdelta);
- Expands an allocated block in place. Expansion will succeed only if the block is the last allocated. Defined only if growDownwards is No.growDownwards.
- pure nothrow @nogc booldeallocate(void[]b);
- Deallocatesb. This works only ifbwas obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing.Parameters:void[] bBlock previously obtained by a call to allocate against this allocator (null is allowed). 
- pure nothrow @nogc booldeallocateAll();
- Deallocates all memory allocated by this region, which can be subsequently reused for new allocations.
- pure nothrow @nogc @trusted Ternaryowns(const void[]b) const;
- Queries whetherbhas been allocated with this region.Parameters:void[] bArbitrary block of memory (null is allowed; owns(null) returns false).Returns:true ifbhas been allocated with this region, false otherwise.
- pure nothrow @nogc @safe Ternaryempty() const;
- Returns Ternary.yes if no memory has been allocated in this region, Ternary.no otherwise. (Never returns Ternary.unknown.)
- pure nothrow @nogc @safe size_tavailable() const;
- Nonstandard property that returns bytes available for allocation.
 
- structBorrowedRegion(uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards);
- ABorrowedRegionallocates directly from a user-provided block of memory.Unlike a Region, aBorrowedRegiondoes 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, aBorrowedRegionbehaves exactly like a Region.Examples:import std.typecons : Ternary; ubyte[1024] store; auto myRegion = BorrowedRegion!(1)(store[]); writeln(myRegion.empty); // Ternary.yes writeln(myRegion.available); // store.length void[] b = myRegion.allocate(101); writeln(b.length); // 101 writeln(myRegion.empty); // Ternary.no writeln(myRegion.owns(b)); // Ternary.yes writeln(myRegion.available); // store.length - b.length void[] b2 = myRegion.allocate(256); // Can only free the most recent allocation writeln(myRegion.deallocate(b)); // false writeln(myRegion.deallocate(b2)); // true myRegion.deallocateAll(); writeln(myRegion.empty); // Ternary.yes - pure nothrow @nogc this(ubyte[]store);
- Constructs a region backed by a user-provided store.Parameters:ubyte[] storeUser-provided store backing up the region. 
- pure nothrow @nogc @safe size_tgoodAllocSize(size_tn) const;
- Rounds the given size to a multiple of the alignment
- aliasalignment= minAlign;
- Alignment offered.
- pure nothrow @nogc @trusted void[]allocate(size_tn);
- Allocatesnbytes of memory. The shortest path involves an alignment adjustment (if alignment > 1), an increment, and a comparison.Parameters:size_t nnumber of bytes to allocate Returns:A properly-aligned buffer of sizenor null if request could not be satisfied.
- pure nothrow @nogc @trusted void[]alignedAllocate(size_tn, uinta);
- Allocatesnbytes of memory aligned at alignmenta.Parameters:size_t nnumber of bytes to allocate uint aalignment for the allocated block Returns:Either a suitable block ofnbytes aligned ata, or null.
- pure nothrow @nogc @trusted void[]allocateAll();
- Allocates and returns all memory available to this region.
- pure nothrow @nogc @safe boolexpand(ref void[]b, size_tdelta);
- Expands an allocated block in place. Expansion will succeed only if the block is the last allocated. Defined only if growDownwards is No.growDownwards.
- pure nothrow @nogc booldeallocate(void[]b);
- Deallocatesb. This works only ifbwas obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing.Parameters:void[] bBlock previously obtained by a call to allocate against this allocator (null is allowed). 
- pure nothrow @nogc booldeallocateAll();
- Deallocates all memory allocated by this region, which can be subsequently reused for new allocations.
- pure nothrow @nogc @trusted Ternaryowns(const void[]b) const;
- Queries whetherbhas been allocated with this region.Parameters:void[] bArbitrary block of memory (null is allowed; owns(null) returns false).Returns:true ifbhas been allocated with this region, false otherwise.
- pure nothrow @nogc @safe Ternaryempty() const;
- Returns Ternary.yes if no memory has been allocated in this region, Ternary.no otherwise. (Never returns Ternary.unknown.)
- pure nothrow @nogc @safe size_tavailable() const;
- Nonstandard property that returns bytes available for allocation.
 
- structInSituRegion(size_t size, size_t minAlign = platformAlignment);
- InSituRegionis 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- InSituRegionis as a stack allocator, it allocates starting at the end on systems where stack grows downwards, such that hot memory is used first.Examples:- // 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 - aliasalignment= 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.InSituRegion!(4096) a1; assert(a1.alignment == platformAlignment); InSituRegion!(4096, 64) a2; assert(a2.alignment == 64); 
- void[]allocate(size_tn);
- 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.
- void[]alignedAllocate(size_tn, uinta);
- As above, but the memory allocated is aligned atabytes.
- booldeallocate(void[]b);
- Deallocatesb. This works only ifbwas obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing. This semantics is tricky and thereforedeallocateis defined only if Region is instantiated with Yes.defineDeallocate as the third template argument.Parameters:void[] bBlock previously obtained by a call to allocate against this allocator (null is allowed). 
- pure nothrow @nogc @safe Ternaryowns(const void[]b);
- Returns Ternary.yes ifbis the result of a previous allocation, Ternary.no otherwise.
- boolexpand(ref void[]b, size_tdelta);
- Expands an allocated block in place. Expansion will succeed only if the block is the last allocated.
- booldeallocateAll();
- Deallocates all memory allocated with this allocator.
- void[]allocateAll();
- Allocates all memory available with this allocator.
- size_tavailable();
- Nonstandard function that returns the bytes available for allocation.
 
- structSbrkRegion(uint minAlign = platformAlignment);
- Allocator backed by sbrk for Posix systems. Due to the fact that sbrk is not thread-safe by design,SbrkRegionuses a mutex internally. This implies that uncontrolled calls to brk and sbrk may affect the workings of SbrkRegion adversely.- static shared SbrkRegioninstance;
- Instance shared by all callers.
- enum uintalignment;
- Standard allocator primitives.
- pure nothrow @nogc @safe size_tgoodAllocSize(size_tn) shared const;
 nothrow @nogc @trusted void[]allocate(size_tbytes) shared;
 nothrow @nogc @trusted void[]alignedAllocate(size_tbytes, uinta) shared;
- Rounds the given size to a multiple of thew alignment
- nothrow @nogc @trusted boolexpand(ref void[]b, size_tdelta) shared;
 pure nothrow @nogc @trusted Ternaryowns(const void[]b) shared;
- Theexpandmethod may only succeed if the argument is the last block allocated. In that case,expandattempts to push the break pointer to the right.
- nothrow @nogc booldeallocate(void[]b) shared;
- Thedeallocatemethod only works (and returns true) on systems that support reducing the break address (i.e. accept calls to sbrk with negative offsets). OSX does not accept such. In addition the argument must be the last block allocated.
- nothrow @nogc booldeallocateAll() shared;
- ThedeallocateAllmethod only works (and returns true) on systems that support reducing the break address (i.e. accept calls to sbrk with negative offsets). OSX does not accept such.
- pure nothrow @nogc @safe Ternaryempty() shared;
- Standard allocator API.
 
- structSharedRegion(ParentAllocator, uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards);
- The threadsafe version of the Region allocator. Allocations and deallocations are lock-free based using core.atomic.cas.- ParentAllocatorparent;
- The parent allocator. Depending on whether ParentAllocator holds state or not, this is a member variable or an alias for ParentAllocator.instance.
- pure nothrow @nogc this(ubyte[]store);
 this(size_tn);
- Constructs a region backed by a user-provided store. Assumes the memory was allocated with ParentAllocator.Parameters:ubyte[] storeUser-provided store backing up the region. Assumed to have been allocated with ParentAllocator. size_t nBytes to allocate using ParentAllocator. If parent.allocate( n) returns null, the region will be initialized as empty (correctly initialized but unable to allocate).
- pure nothrow @nogc @safe size_tgoodAllocSize(size_tn) const;
- Rounds the given size to a multiple of the alignment
- aliasalignment= minAlign;
- Alignment offered.
- pure nothrow @nogc @trusted void[]allocate(size_tn);
- Allocatesnbytes of memory. The allocation is served by atomically incrementing a pointer which keeps track of the current used space.Parameters:size_t nnumber of bytes to allocate Returns:A properly-aligned buffer of sizen, or null if request could not be satisfied.
- pure nothrow @nogc booldeallocate(void[]b);
- Deallocatesb. This works only ifbwas obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing.Parameters:void[] bBlock previously obtained by a call to allocate against this allocator (null is allowed). 
- pure nothrow @nogc booldeallocateAll();
- Deallocates all memory allocated by this region, which can be subsequently reused for new allocations.
- pure nothrow @nogc @trusted void[]alignedAllocate(size_tn, uinta);
- Allocatesnbytes of memory aligned at alignmenta.Parameters:size_t nnumber of bytes to allocate uint aalignment for the allocated block Returns:Either a suitable block ofnbytes aligned ata, or null.
- pure nothrow @nogc @trusted Ternaryowns(const void[]b) const;
- Queries whetherbhas been allocated with this region.Parameters:void[] bArbitrary block of memory (null is allowed; owns(null) returns false).Returns:true ifbhas been allocated with this region, false otherwise.
- pure nothrow @nogc @safe Ternaryempty() const;
- Returns Ternary.yes if no memory has been allocated in this region, Ternary.no otherwise. (Never returns Ternary.unknown.)
 
- structSharedBorrowedRegion(uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards);
- ASharedBorrowedRegionallocates directly from a user-provided block of memory.Unlike a SharedRegion, aSharedBorrowedRegiondoes 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, aSharedBorrowedRegionbehaves exactly like a SharedRegion.- pure nothrow @nogc this(ubyte[]store) shared;
- Constructs a region backed by a user-provided store.Parameters:ubyte[] storeUser-provided store backing up the region. Must not be aliased. 
- pure nothrow @nogc @safe size_tgoodAllocSize(size_tn) shared const;
- Rounds the given size to a multiple of the alignment
- aliasalignment= minAlign;
- Alignment offered.
- pure nothrow @nogc @trusted void[]allocate(size_tn) shared;
- Allocatesnbytes of memory. The allocation is served by atomically incrementing a pointer which keeps track of the current used space.Parameters:size_t nnumber of bytes to allocate Returns:A properly-aligned buffer of sizen, or null if request could not be satisfied.
- pure nothrow @nogc @trusted void[]alignedAllocate(size_tn, uinta) shared;
- Allocatesnbytes of memory aligned at alignmenta.Parameters:size_t nnumber of bytes to allocate uint aalignment for the allocated block Returns:Either a suitable block ofnbytes aligned ata, or null.
- pure nothrow @nogc booldeallocate(void[]b) shared;
- Deallocatesb. This works only ifbwas obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing.Parameters:void[] bBlock previously obtained by a call to allocate against this allocator (null is allowed). 
- pure nothrow @nogc booldeallocateAll() shared;
- Deallocates all memory allocated by this region, which can be subsequently reused for new allocations.
- pure nothrow @nogc @trusted Ternaryowns(const void[]b) shared const;
- Queries whetherbhas been allocated with this region.Parameters:void[] bArbitrary block of memory (null is allowed; owns(null) returns false).Returns:true ifbhas been allocated with this region, false otherwise.
- pure nothrow @nogc @safe Ternaryempty() shared const;
- Returns Ternary.yes if no memory has been allocated in this region, Ternary.no otherwise. (Never returns Ternary.unknown.)
 
Copyright © 1999-2025 by the D Language Foundation | Page generated by
Ddoc on Mon Mar 31 10:28:19 2025