AuroraRuntime/Include/Aurora/Memory/Heap.hpp

/***
    Copyright (C) 2021 J Reece Wilson (a/k/a "Reece"). All rights reserved.

    File: Heap.hpp
    Date: 2021-6-9
    Author: Reece
***/
#pragma once

namespace Aurora::Memory
{
    struct ProxyHeap;
    static const AuUInt8 kHeapSize  = 128;
    static const AuUInt8 kHeap2Size = 255;

    using HeapAccessor = AuHeapAccessor;
    using Heap = AuHeap;

    struct HeapAdapterHandle
    {
        void *pReserved[2];
    };

    struct HeapAdapterInterface
    {
        HeapAdapterHandle handle;

    // Required:
        void *(*  fAllocate)(HeapAdapterHandle *pHandle,
                             AuUInt uLength,
                             AuUInt uAlignment) = nullptr;

    // Required:
        void   (* fFree)(HeapAdapterHandle *pHandle,
                         void *pPointer) = nullptr;

    // Optional:
        AuUInt (* fGetBlockSize)(HeapAdapterHandle *pHandle,
                                 void *pPointer) = nullptr;

    // Optional:
        void (* fHeapDestroy)(HeapAdapterHandle *pHandle) = nullptr;

    // 
        bool bHasAlignmentAwareness {};
    };

    /**
     * Returns a heap interface backed by the default allocator
     */
    AUKN_SHARED_API(DefaultDiscontiguousHeap, Heap);

    inline Heap *GetDefaultDiscontiguousHeap()
    {
        return DefaultDiscontiguousHeapNew();
    }

    inline AuSPtr<Heap> GetDefaultDiscontiguousHeapShared()
    {
        // Might not allocate the control block under some STLs, unlike DefaultDiscontiguousHeapSharedShared() which will generally always allocate a control block under most STLs
        return AuUnsafeRaiiToShared(GetDefaultDiscontiguousHeap());
    }

    /**
     * Allocates uLength amount of contiguous virtual memory
     * @return a heap backed by uLength bytes of virtual memory
     * @warning the SOO variant cannot guarantee release-on-last-free and will panic if uLength cannot be allocated. Use AllocHeap[Shared/Unique/New](uLength) instead.
     */
    AUKN_SHARED_SOO2_NCM(AllocHeap, Heap, kHeapSize, ((AuUInt, uLength)),
                         AuUInt uLength);

    /**
     * @warning the SOO variant cannot guarantee release-on-last-free and will panic if an invalid memory handle is provided.
     */
    AUKN_SHARED_SOO2_NCM(RequestHeapOfRegion, Heap, kHeapSize, ((const MemoryViewWrite &, memory)),
                         const MemoryViewWrite &memory);

    /**
     * @warning the SOO variant cannot guarantee release-on-last-free and will panic if an invalid memory handle is provided.
     */
    AUKN_SHARED_SOO2_NCM(RequestHeapOfSharedRegion, Heap, kHeapSize, ((const AuSPtr<MemoryViewWrite> &, memory)),
                         const AuSPtr<MemoryViewWrite> &pMemory);

    /**
     * Proxies an existing heap with encapsulated statistics.
     * This is intended for debugging purposes when accurate heap stats of a heap-subset are desired.
     * @warning this heap cannot guarantee release-on-last-free
     */
    AUKN_SHARED_SOO2_NCM(HeapProxy, Heap, kHeap2Size, ((const AuSPtr<Heap> &, pHead)),
                         const AuSPtr<Heap> &pHead);

    /**
     * Proxies an existing heap with encapsulated statistics and leak detector
     * This is intended for debugging purposes when accurate heap stats of a heap-subset are desired.
     * @warning this heap cannot guarantee release-on-last-free
    */
    AUKN_SHARED_SOO2_NCM(HeapProxyEx, Heap, kHeap2Size, ((const AuSPtr<Heap> &, pHead), (LeakFinderAlloc_f, pfAlloc), (LeakFinderFree_f, pfFree)),
                         const AuSPtr<Heap> &pHead,
                         LeakFinderAlloc_f pfAlloc,
                         LeakFinderFree_f pfFree);

    /**
     * Proxies an existing heap allocator library of a malloc and free; bonus points for aligned malloc, get allocation size, and destroy 
     */
    AUKN_SHARED_SOO2_NCM(HeapAdapter, Heap, kHeap2Size, ((const HeapAdapterInterface &, adapterInterface)),
                         const HeapAdapterInterface &adapterInterface);

#if defined(AURORA_IS_MODERNNT_DERIVED)
    AUKN_SHARED_SOO2_NCM(HeapWin32Adapter, Heap, kHeap2Size, ((void *, hHeap)), void *hHeap);
#endif
}