Misaki
aae8e2826f
Refactor to use MHP_ENABLE_SAFETY_CHECKS, MHP_ENABLE_STACKTRACE, and MHP_ENABLE_MIMALLOC for feature toggling. Remove FreeList allocator in JobSchedular and debug-layer code, simplifying memory management. Improve memory leak detection and reporting, update memory allocation API, and guard all safety/debug features with new defines. Update csproj files, README, and code samples to match new API and toggles. Fix and improve collection types for correct behavior with and without safety checks. The codebase is now more modular and easier to configure for different build environments. BREAKING CHANGE: Old defines (ENABLE_SAFETY_CHECKS, ENABLE_DEBUG_LAYER, ENABLE_MIMALLOC) are replaced with MHP_* equivalents. FreeList allocator and related debug features are removed. Some APIs and behaviors have changed for safety/debug configuration.
78 lines
2.5 KiB
Markdown
78 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```csharp
|
|
var opts = new AllocationManagerInitOpts
|
|
{
|
|
ArenaCapacity = 1024 * 1024,
|
|
StackCapacity = 1024 * 1024,
|
|
FreeListConcurrencyLevel = 1
|
|
};
|
|
|
|
AllocationManager.Initialize(opts);
|
|
|
|
var arr = new UnsafeArray<int>(10, Allocator.Persistent);
|
|
|
|
// Use the array
|
|
|
|
arr.Dispose();
|
|
|
|
AllocationManager.Dispose();
|
|
```
|
|
|
|
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.
|
|
> Which means if you disable the safety checks, the library will not perform any safety checks 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.
|
|
|
|
## Package reference
|
|
|
|
```bash
|
|
dotnet add package Misaki.HighPerformance.LowLevel
|
|
```
|
|
|
|
## Notes
|
|
|
|
This project targets `net10.0`, enables unsafe code, and is packaged as content files for downstream consumption.
|