[Feature Proposal] NativeArena for Scoped Native Memory Allocation

The proposal names the CommunityToolkit.HighPerformance.Buffers namespace and provides a prototype with unit tests, NativeBlockPool, and BenchmarkDotNet benchmarks. Start by reviewing that prototype and the existing buffer APIs in the repository. Done means the proposed NativeArena API is implemented with tests covering allocation, alignment, reset, and disposal behavior.

[Feature Proposal] NativeArena for Scoped Native Memory Allocation

Overview

CommunityToolkit.HighPerformance provides specialized high-throughput memory and buffer primitives for scenarios where standard BCL abstractions are either too general or impose GC/allocation overhead.

In high-performance workloads—such as document parsing, serialization, game loops, native interop, and protocol decoding—applications frequently need to allocate many small unmanaged data structures or scratch buffers whose lifetimes are strictly bounded to a single operation (e.g., per-request or per-frame).

Currently, developers using NativeMemory.Alloc / Free incur significant OS heap allocation overhead for each individual buffer and must track the disposal of every pointer manually. ArrayPool<T> mitigates managed GC overhead, but is restricted to managed arrays, requires individual return calls, and does not provide native pointer semantics or memory alignment guarantees.

We propose introducing NativeArena into CommunityToolkit.HighPerformance.Buffers. It is a fast, thread-confined chunked bump allocator that allows multiple unmanaged allocations to share a single lifetime, released in bulk upon disposal or reused with zero allocations via Reset().

---

API breakdown

namespace CommunityToolkit.HighPerformance.Buffers;

/// <summary>
/// Configuration options for <see cref="NativeArena"/>.
/// </summary>
public sealed class NativeArenaOptions
{
    public nuint ChunkSize { get; init; } = 64 * 1024;
    public nuint DefaultAlignment { get; init; } = 16;
    public bool ZeroInitialize { get; init; } = false;
    public NativeBlockPool? BlockPool { get; init; }

    public static NativeArenaOptions Default { get; }
    public static NativeArenaOptions Pooled { get; }
}

/// <summary>
/// A fast, scoped bump allocator for native memory allocations sharing a single lifetime.
/// </summary>
public sealed unsafe class NativeArena : IDisposable
{
    public NativeArena(NativeArenaOptions? options = null);
    public static NativeArena Create(NativeArenaOptions? options = null);

    // Raw pointer allocation
    public void* Allocate(nuint byteCount, nuint alignment = 0);

    // Type-safe allocation helpers
    public ref T Allocate<T>() where T : unmanaged;
    public Span<T> AllocateSpan<T>(int count) where T : unmanaged;

    // Zero-allocation reuse
    public void Reset();

    // Bulk cleanup
    public void Dispose();
}

---

Usage example

1. Basic Scoped Native Scratchpad

using var arena = NativeArena.Create();

// Fast bump allocation with guaranteed alignment
Span<int> indices = arena.AllocateSpan<int>(1024);
ref Matrix4x4 matrix = ref arena.Allocate<Matrix4x4>();

// All native memory is released at the end of the using scope

2. Per-Frame / Per-Request Reusable Arena

// Retain the arena across iterations without re-allocating chunks
using var arena = NativeArena.Create(NativeArenaOptions.Pooled);

while (server.TryReadPacket(out var packet))
{
    arena.Reset(); // Rewinds offsets to 0 with 0 OS allocations

    void* header = arena.Allocate(64);
    Span<byte> payload = arena.AllocateSpan<byte>(packet.Length);
    packet.CopyTo(payload);

    ProcessNativePacket(header, payload);
}

---

Breaking change?

No, this is a purely additive API to CommunityToolkit.HighPerformance.

---

Alternatives

1. NativeMemory.Alloc / NativeMemory.Free: Each allocation requires an individual OS allocator roundtrip and explicit tracking/freeing.
2. ArrayPool<T>: Only manages managed arrays (T[]), does not support unmanaged pointers without pinning, lacks custom alignment controls, and requires returning each rented buffer individually.
3. stackalloc: Useful for tiny allocations, but can cause stack overflows for larger or dynamic payloads, and cannot outlive the immediate method frame.
4. Custom per-project allocators: Many game engines and native wrappers currently write custom bump allocators in C#.

---

Additional context

• Discussion History: This was previously discussed as a potential BCL candidate in dotnet/runtime#135986. The runtime team noted that because arena allocators depend heavily on workload-specific policies (single-threaded vs. concurrent, chunk sizing, and chunk pooling strategies), it is far better suited for a high-performance utility library like CommunityToolkit.HighPerformance where developers opt into specific allocation characteristics.
• Prototype Available: A working prototype featuring unit tests, configurable chunk sizing, block pooling (NativeBlockPool), and BenchmarkDotNet benchmarks is available and ready for review.

---

Help us help you

Yes, I'd like to be assigned to work on this item