Misaki
69b054e81d
Introduce VirtualStack allocator, refactor memory management to use virtual memory stacks, and update documentation. Added VirtualStack as a new stack allocator using virtual memory, replaced Stack with VirtualStack in allocation manager and related APIs, and updated TempJobAllocator to use VirtualArena. Introduced AllocationManagerInitOpts for allocator configuration. Replaced ENABLE_COLLECTION_CHECKS with ENABLE_SAFETY_CHECKS for safety checks. Removed Result.cs and updated project files and examples. Added comprehensive README files for all major packages and improved root documentation. BREAKING CHANGE: Stack allocator replaced by VirtualStack; TempJobAllocator and AllocationManager initialization signatures changed; Result types removed.
156 lines
5.1 KiB
Markdown
156 lines
5.1 KiB
Markdown
# Misaki.HighPerformance
|
|
|
|
A collection of high-performance C# libraries focused on low allocation, low overhead, and systems-level control.
|
|
|
|
The solution is organized around a few core goals:
|
|
|
|
- fast collections and reusable memory primitives
|
|
- unsafe and low-level building blocks when performance matters
|
|
- SIMD/SPMD-friendly mathematics
|
|
- a zero-allocation job system
|
|
- STB-based image loading and translation helpers
|
|
- analyzers and code fixes that help avoid accidental performance regressions
|
|
|
|
Most runtime projects target **.NET 10** and enable **unsafe** code where needed. Analyzer packages target **.NET Standard 2.0**.
|
|
|
|
## Packages
|
|
|
|
Each major package has its own README for project-specific guidance.
|
|
|
|
| Project | Purpose |
|
|
| --- | --- |
|
|
| [`Misaki.HighPerformance`](Misaki.HighPerformance/README.md) | Core collection utilities, pools, slot maps, sparse sets, and shared helpers. |
|
|
| [`Misaki.HighPerformance.LowLevel`](Misaki.HighPerformance.LowLevel/README.md) | Unsafe collections, allocators, arenas, fixed strings, memory utilities, and other low-level primitives. |
|
|
| [`Misaki.HighPerformance.Mathematics`](Misaki.HighPerformance.Mathematics/README.md) | Math helpers, geometry types, SIMD-friendly helpers, numeric constants, and vector operations. |
|
|
| [`Misaki.HighPerformance.Mathematics.SPMD`](Misaki.HighPerformance.Mathematics.SPMD/README.md) | SPMD-oriented math helpers, lane abstractions, and vector template infrastructure. |
|
|
| [`Misaki.HighPerformance.Jobs`](Misaki.HighPerformance.Jobs/README.md) | Job scheduling, worker threads, handles, dependency management, and temporary job allocation. |
|
|
| [`Misaki.HighPerformance.Image`](Misaki.HighPerformance.Image/README.md) | STB image decoding/translation utilities, image metadata, animated image support, and runtime helpers. |
|
|
|
|
## Highlights
|
|
|
|
### Low-level collections and memory management
|
|
|
|
The low-level layer includes building blocks such as:
|
|
|
|
- `UnsafeArray<T>`
|
|
- `UnsafeList<T>`
|
|
- `UnsafeQueue<T>`
|
|
- `UnsafeStack<T>`
|
|
- `UnsafeHashMap<TKey, TValue>`
|
|
- `UnsafeHashSet<T>`
|
|
- `UnsafeSparseSet<T>`
|
|
- `UnsafeSlotMap<T>`
|
|
- `MemoryPool`
|
|
- `VirtualArena`
|
|
- `DynamicArena`
|
|
- `AllocationManager`
|
|
- `FreeList`
|
|
- `FixedString` and `FixedText`
|
|
|
|
These types are designed for scenarios where allocation patterns, data locality, and explicit lifetime management matter.
|
|
|
|
### Mathematics for performance-sensitive code
|
|
|
|
The mathematics layer provides:
|
|
|
|
- `math` constants and helpers
|
|
- custom numeric types and vector extensions
|
|
- geometry primitives such as `AABB`, `OBB`, `Plane`, and `SphereBounds`
|
|
- SIMD-friendly operations through `System.Runtime.Intrinsics`
|
|
|
|
### Job system
|
|
|
|
The job system is designed for work scheduling with minimal overhead and dependency tracking.
|
|
It supports:
|
|
|
|
- single jobs
|
|
- parallel-for style jobs
|
|
- parallel jobs with batching
|
|
- job dependencies
|
|
- worker threads
|
|
- temporary frame-based allocation
|
|
|
|
### Image loading
|
|
|
|
The image package wraps STB-based decoding workflows and includes support for image metadata, animated frames, and runtime statistics.
|
|
|
|
## Getting started
|
|
|
|
### Install the packages
|
|
|
|
```bash
|
|
dotnet add package Misaki.HighPerformance
|
|
dotnet add package Misaki.HighPerformance.LowLevel
|
|
dotnet add package Misaki.HighPerformance.Mathematics
|
|
dotnet add package Misaki.HighPerformance.Jobs
|
|
dotnet add package Misaki.HighPerformance.Image
|
|
```
|
|
|
|
### Reference only what you need
|
|
|
|
The solution is split into smaller packages so you can bring in only the pieces required by your application.
|
|
For example:
|
|
|
|
- use `Misaki.HighPerformance` for lightweight collection utilities
|
|
- add `Misaki.HighPerformance.LowLevel` when you need unsafe memory primitives
|
|
- use `Misaki.HighPerformance.Mathematics` for fast numeric and geometry work
|
|
- use `Misaki.HighPerformance.Jobs` for background work scheduling
|
|
- use `Misaki.HighPerformance.Image` for image decoding
|
|
|
|
## Quick examples
|
|
|
|
### Dynamic array
|
|
|
|
```csharp
|
|
using Misaki.HighPerformance.Collections;
|
|
|
|
var values = new DynamicArray<int>();
|
|
values.Add(10);
|
|
values.Add(20);
|
|
|
|
Span<int> span = values.AsSpan();
|
|
```
|
|
|
|
### Math helpers
|
|
|
|
```csharp
|
|
using Misaki.HighPerformance.Mathematics;
|
|
|
|
float angle = math.radians(90f);
|
|
float tau = math.TAU;
|
|
```
|
|
|
|
### Low-level memory usage
|
|
|
|
The low-level project is intended for advanced scenarios where explicit allocation and lifetime control are required.
|
|
Prefer the safer higher-level projects when they already meet your needs.
|
|
|
|
## Building the solution
|
|
|
|
Open the solution in Visual Studio or build from the command line:
|
|
|
|
```bash
|
|
dotnet build
|
|
```
|
|
|
|
Some projects use unsafe code and source generation. Make sure you are building with a compatible .NET SDK and that your environment allows those features.
|
|
|
|
## Design goals
|
|
|
|
- keep allocations under control
|
|
- favor cache-friendly data structures
|
|
- expose low-level primitives without unnecessary abstraction
|
|
- support high-performance math and job execution paths
|
|
- provide analyzers to help keep code fast
|
|
|
|
## Repository notes
|
|
|
|
- Most runtime projects target `net10.0`
|
|
- Analyzer projects target `netstandard2.0`
|
|
- Several projects enable packaging on build
|
|
- Unsafe code is used intentionally in the low-level, math, job, and image layers
|
|
|
|
## License
|
|
|
|
See the repository license if one is provided.
|