67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# Introduction
|
|
|
|
The low-level library provides unsafe collections, allocators, and memory-management primitives for high-performance C#. It gives you explicit control over allocation, layout, and ownership so you can build systems that run without GC interference.
|
|
|
|
## Why a dedicated low-level library?
|
|
|
|
Standard .NET memory management wasn't designed for allocation-heavy game and simulation workloads:
|
|
|
|
- `NativeMemory.Alloc` and `Marshal.AllocHGlobal` provide raw allocation but no collection types, no lifetime tracking, and no safety checks.
|
|
- The BCL collections (`List<T>`, `Dictionary<K,V>`) allocate on the managed heap, producing GC pressure in tight loops.
|
|
- `Span<T>` and `Memory<T>` avoid allocations but don't own their memory and can't manage lifetimes across asynchronous boundaries.
|
|
|
|
This library solves these problems with pluggable allocators, unsafe collections that wrap raw pointers, and a safety check system that can be compiled away in release builds.
|
|
|
|
## Feature highlights
|
|
|
|
| Feature | Description |
|
|
|---|---|
|
|
| Pluggable allocators | Every allocation passes through an `AllocationHandle` — choose the right allocator per use case |
|
|
| Built-in allocators | `Temp`, `FreeList`, `Persistent`, `TLSF` — or use `MemoryPool` with heap-based `Arena` and `Stack` |
|
|
| Unsafe collections | Arrays, lists, queues, stacks, hash maps, hash sets, sparse sets, slot maps, chunked lists |
|
|
| Parallel-aware types | Lock-free queue and concurrent hash map with parallel reader/writer views |
|
|
| Fixed-size text | Stack-only `FixedString` (UTF-16) and `FixedText` (UTF-8) for zero-allocation string operations |
|
|
| Compile-time safety | `MHP_ENABLE_SAFETY_CHECKS` enables bounds checking, use-after-free detection, and leak tracking — compiled away in release |
|
|
| Custom allocators | Implement your own allocator by populating an `AllocationHandle` with function pointers |
|
|
| `MemoryPool<TAllocator>` | Scope allocators to a method or algorithm without touching the global state |
|
|
| Struct semantics | All collections are structs with no managed handles — no GC overhead, pass by `ref` for mutation |
|
|
|
|
## Basic usage
|
|
|
|
```csharp
|
|
using Misaki.HighPerformance.LowLevel.Buffer;
|
|
|
|
AllocationManager.Initialize();
|
|
|
|
var array = new UnsafeArray<int>(10, AllocationHandle.Persistent);
|
|
|
|
array[0] = 42;
|
|
Console.WriteLine(array[0]); // Output: 42
|
|
|
|
array.Dispose();
|
|
AllocationManager.Dispose();
|
|
```
|
|
|
|
## Who this is for
|
|
|
|
- Custom game engine developers who need allocation control without GC pauses
|
|
- Systems programmers building runtime components, job schedulers, or custom allocators
|
|
- .NET developers who have hit performance limits with managed collections in hot paths
|
|
|
|
## Requirements
|
|
|
|
- .NET 10.0 or later
|
|
- `unsafe` code enabled (`<AllowUnsafeBlocks>true</AllowUnsafeBlocks>`)
|
|
|
|
## Install
|
|
|
|
```bash
|
|
dotnet add package Misaki.HighPerformance.LowLevel
|
|
```
|
|
|
|
## Additional resources
|
|
|
|
- [Architecture overview](architecture-overview.md) — understand the allocation model and design philosophy
|
|
- [Allocators](allocators.md) — learn about each built-in allocator and how to create custom ones
|
|
- [Collection types](collection-types.md) — explore all available data structures
|