ZeroAlloc.Collections 1.2.3

ZeroAlloc.Collections

Pooled and stack-only counterparts to List<T>, Dictionary<TKey,TValue>, Stack<T> and Queue<T> whose ref struct forms add, look up and enumerate with 0 B allocated, NativeAOT-ready.

Why ZeroAlloc.Collections

• 0 B on the hot path, asserted in CI. The ref struct collections add, look up and enumerate with 0 B allocated per call; AllocationTests fails CI if any of them allocates.
• About 2× faster than the BCL for lists, stacks and dictionaries. Adding 1,000 items to a PooledList<int> takes 0.51× the time of List<int>, which allocates 8,424 B in the same run.
• Works under NativeAOT and trimming. No reflection and no runtime code generation; every PR publishes and runs an AOT sample.
• Compile-time diagnostics instead of runtime surprises. ZAC001 warns when a pooled collection is never disposed, so a buffer that would never return to the pool is a build warning.

Install

dotnet add package ZeroAlloc.Collections

Quick start

using ZeroAlloc.Collections;

string[] order = ["apple", "pear", "apple", "kiwi"];

// Rents its entries from ArrayPool<T>.Shared and returns them on Dispose.
using var prices = new SpanDictionary<string, decimal>(capacity: 16);
prices.Add("apple", 0.50m);
prices.Add("pear", 0.75m);

// Lives on the stack: no heap allocation at all.
var basket = new FixedSizeList<decimal>(stackalloc decimal[8]);
foreach (var item in order)
    if (prices.TryGetValue(item, out var price)) basket.Add(price);

decimal total = 0;
foreach (var p in basket) total += p;
Console.WriteLine($"{basket.Count} items, {total}"); // 3 items, 1.75

What you get

• Two forms of each: a ref struct for synchronous hot paths, and a Heap* class for fields, async code and APIs that take IList<T>, IReadOnlyCollection<T> or IDictionary<TKey,TValue>.
• Span<T> access to the list and stack contents for zero-copy loops.
• Source generators that emit type-specific collections from [ZeroAllocList(typeof(T))]. See source generators.
• Targets netstandard2.1, net8.0 and net9.0.

Performance

BenchmarkDotNet, N = 1,000. Time is the same-run ratio against the BCL type; allocations are exact.

RingBuffer<T> and PooledQueue<T> trade speed for allocation, and the Heap* classes allocate one enumerator per foreach. Every workload, with the full numbers: docs/performance.md.

Learn more

• Documentation: collections.zeroalloc.net, including getting started, the cookbook and diagnostics.
• Related packages: ZeroAlloc.Inject and ZeroAlloc.Analyzers.
• Contributing: issues and pull requests are welcome on GitHub.
• CHANGELOG.

License

MIT. See LICENSE.