116 lines
5.1 KiB
C#
116 lines
5.1 KiB
C#
// -----------------------------------------------------------------------------
|
|
// file="SlabAllocator"
|
|
// Project: StgSharp
|
|
// Copyright (c) Nitload.
|
|
// SPDX-License-Identifier: MIT
|
|
// -----------------------------------------------------------------------------
|
|
|
|
using StgSharp.HighPerformance.Memory;
|
|
using System;
|
|
|
|
namespace StgSharp.HighPerformance.Memory
|
|
{
|
|
public static class SlabAllocator
|
|
{
|
|
|
|
/// <summary>
|
|
/// Creates a new SLAB allocator instance with the specified configuration.
|
|
/// </summary>
|
|
/// <param name="count">
|
|
/// Initial number of objects that can be allocated.
|
|
/// </param>
|
|
/// <param name="layout">
|
|
/// Memory layout strategy for the SLAB allocator.
|
|
/// </param>
|
|
/// <param name="concurrentSupport">
|
|
/// Whether to enable concurrent access support.
|
|
/// </param>
|
|
/// <returns>
|
|
/// A new SLAB allocator instance.
|
|
/// </returns>
|
|
/// <exception cref="ArgumentOutOfRangeException">
|
|
/// Thrown when an invalid layout is specified.
|
|
/// </exception>
|
|
/// <exception cref="NotSupportedException">
|
|
/// Thrown when requesting unsupported configurations.
|
|
/// </exception>
|
|
/// <remarks>
|
|
/// <para><strong> Important Threading Considerations: </strong></para> <para>While SLAB
|
|
/// allocators themselves may be designed for single-threaded use, allocated objects are
|
|
/// frequently shared across multiple threads in real-world applications. Due to the
|
|
/// special implementation of expandable concurrent sequential SLAB allocators, they rely
|
|
/// on internal expansion locks to ensure that memory buffer expansions (which involve
|
|
/// copying the entire buffer to a new location) do not occur while other threads are
|
|
/// reading from allocated regions. </para> <para><strong> Sequential Layout Limitations:
|
|
/// </strong><br /> Sequential layout SLAB allocators cannot provide a single- threaded
|
|
/// version because:<list type="bullet"><item><description> They use contiguous memory
|
|
/// layout that requires buffer expansion when capacity is exceeded
|
|
/// </description></item><item><description> Buffer expansion involves copying all
|
|
/// existing data to a new memory location </description></item><item><description>Without
|
|
/// proper synchronization, concurrent access to allocated objects during synchronization,
|
|
/// concurrent access to allocated objects during expansion would cause memory
|
|
/// corruption</description></item><item><description>The expansion lock mechanism is
|
|
/// essential even if allocation itself is single- threaded
|
|
/// </description></item></list></para> <para><strong> Chunked Layout: </strong><br />
|
|
/// Chunked layout allocators can optionally provide single-threaded versions since they
|
|
/// don't require buffer expansion and copying. Each chunk is allocated independently,
|
|
/// avoiding the memory relocation issues present in sequential layouts. </para>
|
|
/// </remarks>
|
|
public static SlabAllocator<T> Create<T>(
|
|
nuint count,
|
|
SlabBufferLayout layout,
|
|
bool concurrentSupport = true
|
|
) where T : unmanaged
|
|
{
|
|
return layout switch
|
|
{
|
|
SlabBufferLayout.Sequential => concurrentSupport ?
|
|
new ConcurrentSequentialSlabAllocator<T>(count) :
|
|
throw (new NotSupportedException("Non-concurrent version of sequential layout SLAB is not supported due to expansion lock requirements for memory safety during buffer expansion.")),
|
|
SlabBufferLayout.Chunked => concurrentSupport ?
|
|
new ConcurrentChunkedSlabAllocator<T>(count) :
|
|
new ChunkedSlabAllocator<T>(count),
|
|
_ => throw (new ArgumentOutOfRangeException(nameof(layout), layout, null))
|
|
};
|
|
}
|
|
|
|
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
|
public static SlabAllocator<T> FromBuffer<T>(
|
|
nuint buffer,
|
|
nuint count,
|
|
Action<nuint> freeHandle
|
|
) where T : unmanaged
|
|
{
|
|
return new FixedSlabAllocator<T>(buffer, count, freeHandle);
|
|
}
|
|
|
|
}
|
|
|
|
public abstract class SlabAllocator<T> : IDisposable where T : unmanaged
|
|
{
|
|
|
|
public abstract nuint Allocate();
|
|
|
|
public abstract void Dispose();
|
|
|
|
public abstract void EnterBufferReading();
|
|
|
|
public abstract void ExitBufferReading();
|
|
|
|
public abstract void Free(
|
|
nuint index
|
|
);
|
|
|
|
public abstract SlabAllocationHandle<T> ReadAllocation();
|
|
|
|
}
|
|
|
|
public enum SlabBufferLayout
|
|
{
|
|
|
|
Sequential,
|
|
Chunked
|
|
|
|
}
|
|
}
|