Arena

Source: lib/Arena.cs

This page is generated from the source by scripts/gen-reference.py.

Growable arena (bump) allocator for zero mode. Compiled under the C# 15 updated memory safety rules (see build.sh).

An arena hands out memory by moving a pointer forward and frees everything at once. Create one per lifetime: one for the whole run, one per request or frame, one for scratch work.

Arena arena = Arena.Create();
Point* p = arena.Alloc<Point>();
...
unsafe { arena.Reset(); }      // everything allocated from it is gone
  • Arena is a handle (one pointer), so copies refer to the same arena, like passing Arena* in C. A default(Arena) is "not created": every allocation from it returns null.

  • Normal blocks grow in a Fibonacci sequence: 128, 128, 256, 384, 640, ...

  • An allocation that doesn't fit the next normal block gets a dedicated block of its own and leaves that sequence alone.

  • Every allocation picks its alignment (any power of two, default 16).

  • Allocations fail by returning null; arena state is untouched on failure. An arena created with stopOnOutOfMemory: true ends the program instead when memory runs out, so nothing has to check for that.

  • Save() and Restore() free only what was allocated in between, for temporary work in an arena that also holds longer-lived data. Don't let an older collection grow in between (see Restore). OpenScope() pairs the two with a using block, so they can't get out of order.

  • Reset() keeps the capacity by merging all blocks into one, so a steady-state workload (one scratch arena per token, per frame, ...) stops calling malloc after the first round.

  • AllocateObjectsHere() sends every ordinary allocation (new, closures, strings, boxing) to the arena until the scope closes, so code that would leak frees its objects with the arena. See it for the rules.

  • Not thread-safe: use one arena per thread.

  • Arena.DebugChecks = true (set it first thing in Main) makes arenas created afterwards fill freed memory with 0xDD bytes, and makes List, Dict and StrBuilder stop the program when used after their memory was freed. See DebugChecks for what that does and doesn't catch.

  • For finding out what an arena does: give it a name in Create (failure messages then say which arena), print its blocks with Dump(), and read PeakUsed after a run to choose the first block's size.

Allocating is safe: a pointer is harmless until it is dereferenced, and dereferencing needs an unsafe context anyway. Restore(), Reset() and Destroy() are the dangerous operations, so they are marked unsafe: the caller promises that nothing still points at the memory they free.

Members

DefaultAlign

public const nuint DefaultAlign = 16

DebugChecks

public static bool DebugChecks

Debugging aid, off by default. While on:

  • Arenas created from then on fill memory with 0xDD bytes when it is freed (Restore, Reset, Destroy) and when a block is first obtained. A stale pointer then reads 0xDDDDDDDD instead of plausible old data, and so does memory allocated with zero: false and never written.

  • List, Dict and StrBuilder check on every use that their buffer is still allocated, all of it, and end the program with a message if it isn't. That catches a collection used after its arena was reset, and one that grew after a Save() (into a new buffer or in place) and was used after the Restore().

It can't catch everything: once freed memory has been handed out again, a stale pointer into it looks valid. And it costs time: a fill on every free, a check on every collection operation.

Create

public static Arena Create(
    nuint blockSize = 4096,
    string name = null,
    bool stopOnOutOfMemory = false)

Returns a new arena with one block, or a not-created arena if malloc fails. name is for Dump() and failure messages; the arena keeps the reference, so pass a string that outlives it, such as a literal. With stopOnOutOfMemory, running out of memory ends the program with a message, here and in every later allocation, instead of returning null (and instead of List.Add and the like returning false). Use it wherever the program couldn't carry on anyway. Requests that are wrong in themselves (a bad alignment, a negative count) still return null.

IsCreated

public bool IsCreated

BlockCount

public int BlockCount

Used

public nuint Used

Bytes handed out, padding excluded.

Capacity

public nuint Capacity

The sum of all block sizes.

PeakUsed

public nuint PeakUsed

The highest Used has been since the arena was created. A good first block size.

PeakCapacity

public nuint PeakCapacity

The highest Capacity has been since the arena was created.

Name

public string Name

The name given to Create, or null.

NextBlockSize

public nuint NextBlockSize

CurrentBlockSize

public nuint CurrentBlockSize

CurrentBlockFree

public nuint CurrentBlockFree

Alloc

public void* Alloc(nuint size, nuint align = DefaultAlign, bool zero = true)

Returns size bytes aligned to align, or null.

public T* Alloc<T>(nuint align = DefaultAlign) where T : unmanaged

AllocArray

public T* AllocArray<T>(
    int count,
    nuint align = DefaultAlign,
    bool zero = true) where T : unmanaged

Returns room for count elements, or null on overflow or OOM.

AllocSpan

public unsafe Span<T> AllocSpan<T>(
    int count,
    nuint align = DefaultAlign) where T : unmanaged

Like AllocArray, wrapped in a span. Returns an empty span on failure.

Safety: The span points into the arena. Don't use it after the memory is freed.

TryExtend

public bool TryExtend(void* allocation, nuint oldSize, nuint newSize)

Grows an allocation in place from oldSize to newSize bytes. This only works for the arena's most recent allocation, and only while its block has room; otherwise it returns false and changes nothing. The added bytes are not zeroed.

Lets a buffer that is still last in the arena grow without leaving its old copy behind.

IsLive

public bool IsLive(void* pointer)

Whether pointer points into memory this arena has handed out and not freed since. Approximate: padding between allocations counts as handed out.

public bool IsLive(void* pointer, nuint size)

Like IsLive(pointer), for all size bytes from pointer: false too if only the end of that range was freed, as happens to a buffer that grew in place after a Save() once the mark is restored.

Save

public Mark Save()

Remembers the arena's current position, for Restore().

Restore

public unsafe void Restore(Mark mark)

Frees everything allocated since mark was saved, and nothing from before it. Marks must be restored newest first: restoring a mark also ends every mark saved after it. A mark from another arena, from before a Reset(), or one that points past what the arena now holds (it was ended by restoring an older mark) ends the program. That last check can miss an ended mark once enough has been allocated again to cover its position; OpenScope() rules the mistake out instead.

Safety: Every pointer, span and collection allocated since the mark becomes dangling. That includes the buffer of an older List, Dict or StrBuilder that grew after the mark: its new buffer is freed here while the collection still points at it, and later allocations overwrite it without any error. So between Save() and Restore(), only add to collections created after the mark. For temporary work that adds to long-lived collections, use a separate scratch arena instead.

OpenScope

public unsafe Scope OpenScope()

Save() for a using block: leaving the block restores the mark, so the two can't be left unpaired or get out of order.

Arena.Scope temp;
unsafe { temp = arena.OpenScope(); } // SAFETY: nothing from inside is used after the block
using (temp)
{
   ... temporary allocations ...
}

Safety: As for Restore: everything allocated inside the block dangles after it, including the buffer of an older collection that grew inside it.

AllocateObjectsHere

public unsafe ObjectScope AllocateObjectsHere()

Until the returned scope is disposed, every object the program creates (new, boxing, closures, delegates, arrays, string concatenation) is allocated in this arena instead of with calloc, so resetting the arena frees it: ordinary C# stops leaking.

Arena frame = Arena.Create(64 * 1024);
ObjectScope objects;
unsafe { objects = frame.AllocateObjectsHere(); } // SAFETY: see below
using (objects)
{
   ... code that allocates ...
}
unsafe { frame.Reset(); } // SAFETY: nothing from the frame is kept

Scopes nest: disposing one puts back whatever was in effect before it. The arena must outlive the scope. The scope applies only to the thread that opens it: other threads keep allocating as before.

Safety: The objects die with the arena (Reset, Restore, Destroy), so no reference to one may be kept past that: not in a static field, not in an object from outside the scope. That includes what the compiler keeps for you: a lambda that captures nothing is created the first time it runs and then cached in a static field, and a static constructor runs the first time its type is used. If either happens first inside the scope, the cache or the static field points into the arena. Run such code once before opening the scope. With Arena.DebugChecks on when the arena was created, closing the scope checks every static field and stops the program if one points into the arena. The compiler also caches delegates outside static fields: a lambda that captures a variable declared outside the scope is cached in the closure that holds that variable, an object from outside, and the check can't see that. Declare what a lambda inside the scope captures inside the scope too, or in a method called from it.

Dump

public void Dump()

Prints the arena's name, how full it is and its blocks to standard output:

Arena "frame": 920 of 1152 bytes used (peak 920 of 1152), 3 blocks
 block 1: 128 bytes
 block 2: 256 bytes
 block 3: 768 bytes, 88 free (current)

Many small blocks mean the first block is too small for the workload; PeakUsed is the size that would have held everything.

Reset

public unsafe void Reset(bool keepCapacity = true)

Frees every allocation at once. With keepCapacity the blocks are merged into a single block of the same total size; otherwise the arena shrinks back to one initial-size block and the growth sequence restarts.

Safety: Every pointer, span and collection that points into the arena becomes dangling.

Destroy

public unsafe void Destroy()

Returns all memory to the system. This handle becomes not-created.

Safety: Every pointer, span and collection that points into the arena becomes dangling, and so does every other copy of this handle.

Arena.Mark

A point in an arena's history, from Save(). Restore() frees everything allocated after it.

Arena.Scope

A Save() that restores itself: from OpenScope(), for a using block. Leaving the block, by any path, frees what was allocated inside it.

Dispose

public void Dispose()

Arena.ObjectScope

From AllocateObjectsHere, for a using block: disposing it puts back the allocator that was in effect before.

Dispose

public void Dispose()

Puts back the previous allocator; with DebugChecks, also checks that no static field points into the arena.