Misaki.HighPerformance/Misaki.HighPerformance.LowLevel/README.md

Misaki.HighPerformance.LowLevel

Unsafe collections, allocators, and memory-management primitives for high-performance C#.

This package is the lowest-level layer in the solution. It is intended for code that needs explicit control over allocation, layout, and ownership.

What it includes

• unsafe arrays, lists, queues, stacks, hash maps, hash sets, sparse sets, and slot maps
• arenas and allocation helpers
• fixed-size text and string primitives
• memory and unsafe utilities
• pointer wrappers and function pointers
• low-level buffer and lifetime management types

Highlights

• explicit allocation control
• cache-friendly and allocation-aware data structures
• APIs suited for systems programming, jobs, and custom runtime components
• designed to work well with unsafe and AOT-friendly code paths

Main types

• UnsafeArray<T>
• UnsafeList<T>
• UnsafeQueue<T>
• UnsafeStack<T>
• UnsafeHashMap<TKey, TValue>
• UnsafeHashSet<T>
• UnsafeSparseSet<T>
• UnsafeSlotMap<T>
• VirtualArena
• DynamicArena
• MemoryPool
• AllocationManager
• UnsafeUtility
• FixedString
• FixedText

Example

General usage

var opts = new AllocationManagerInitOpts
{
    ArenaCapacity = 1024 * 1024,
    StackCapacity = 1024 * 1024,
};

AllocationManager.Initialize(opts);

var arr = new UnsafeArray<int>(10, AllocationHandle.Persistent);

// Use the array

arr.Dispose();

AllocationManager.Dispose();

Custom memory pool

using var pool = new MemoryPool<TLSF, TLSF.CreationOptions>(new TLSF.CreationOptions { alignment = 16 });
using var array = new UnsafeArray<int>(10, pool.AllocationHandle);

// Use the array

Package reference

dotnet add package Misaki.HighPerformance.LowLevel

Notes

This project targets net10.0, enables unsafe code, and is packaged as content files for downstream consumption.

You can enable debug features for leak detection and use-after-free checks by defining MHP_ENABLE_SAFETY_CHECKS in your project. And define MHP_ENABLE_STACKTRACE to enable additional debug features such as tracking allocations and providing detailed error messages.

If you disable the safety checks, the library will not perform any safety checks, including bounds checking, and provide the maximum performance, and it will be your responsibility to ensure correct usage to avoid memory leaks and undefined behavior. Even IUnsafeCollection.IsCreated will only check if the internal pointer is non-null, without verifying the actual validity of the memory.

You can also define MHP_ENABLE_MIMALLOC to use mimalloc as the underlying allocator instead of the default C allocator.

Using mimalloc requires to install the TerraFX.Interop.Mimalloc package.