// -----------------------------------------------------------------------------
// 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

    }
}