using System.Runtime.InteropServices;

namespace UnmanagedMMU.Allocators
{
    /// <summary>
    /// Interface that defines an Unmanaged allocator
    /// </summary>
    public unsafe interface IUnmanagedAllocator
    {
        /// <summary>
        /// Allocates an unmanaged memory block of the specified size.
        /// </summary>
        /// <param name="size">The number of bytes to allocate.</param>
        /// <returns>
        /// A pointer to the beginning of the allocated memory block,.
        /// </returns>
        void* Alloc(nuint size);

        /// <summary>
        /// Allocates an unmanaged memory block of the specified size with the requested alignment
        /// </summary>
        /// <param name="size">The number of bytes to allocate.</param>
        /// <param name="alignment">The alignment, in bytes, of the block to allocate. This must be a power of <c>2</c></param>
        /// <returns></returns>
        void* AllocAligned(nuint size, nuint alignment);


        /// <summary>
        /// Frees a previously allocated unmanaged memory block.
        /// </summary>
        /// <param name="ptr">A pointer to the beginning of the memory block to free.</param>
        /// <remarks>This method should only be called on with pointers allocated with <see cref="Alloc"/>.</remarks>
        void Free(void* ptr);

        /// <summary>
        /// Frees a previously allocated unmanaged aligned memory block
        /// </summary>
        /// <param name="ptr">A pointer to the beginning of the memory block to free.</param>
        /// <param name="alignment">The alignment that the memory refered to by <paramref name="ptr"/> was aligned at (This parameter can be ignored if the underlying allocator does not need it)</param>
        /// <remarks>This method should only be called on with pointers allocated with <see cref="AllocAligned"/>.</remarks>
        void FreeAligned(void* ptr, nuint alignment = 0);
    }
}