AuroraSupport/AuROXTL
1
1
Fork 0
Code Issues 7 Pull Requests Releases Wiki Activity

[*] Updated auMemoryAllocate.hpp *comment*

Browse Source
This commit is contained in:
Reece Wilson 2024-09-24 12:29:43 +01:00
parent 4d7f4fab7d
commit 58a2456555
1 changed files with 65 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
Include/auROXTL/MemoryModel/auMemoryAllocate.hpp
View File

@ -24,34 +24,74 @@
// AuHUPOf_t<T> AuNullHeapPointer<T>()
// AuUPtr<T> AuNullHeapPointer<T>() [ 2024/09 ]
// AuSPtr<T> AuMakeShared(...)
// AuSPtr<T> AuUnsafeRaiiToShared(T *) [ unsafe ]
// AuSPtr<T> AuUnsafeRaiiToShared(const AuUPtr<T, Deleter> &) [ unsafe ]
// AuSPtr<T> AuUnsafeRaiiToShared(const AuUPtr<T> &) [ unsafe ]
//
// AuSPtr<T> - shared
// (you will probably use me)
// AuSPtr<T> - shared pointer
//
// AuSSPtr<T> - shared (special. if the shared pointer container is too big, this type may shrink it down. )
// (unimportant for regular users)
// AuSSPtr<T> - shared pointer
// (special. if the shared pointer container is too big, this type may shrink it down. )
// ( this maybe useful for storing parent pointers in foreign places or small slots. )
//
// (you will probably use me)
// AuHPtr<T> - unique with immutable instantiated deleter (...<T>) of derived main class (= T)
//
// (unimportant for regular users. only relevant prior to 2024/09, unless C++ STL compat is still required. )
// AuHUPOf_t<T> - unique of a function callback; relevant prior to 2024/09.
// - could be assigned to null with AuNullHeapPointer; relevant prior to 2024/09.
// - use me instead of AuUPtr<T NO DELETER> to be compatible to pre 2024/09 codebases.
// could be assigned to null with AuNullHeapPointer; relevant prior to 2024/09.
// use me instead of AuUPtr<T NO DELETER> to be compatible to pre 2024/09 codebases.
//
// AuUPtr<T, Deleter_t> - close to what youd expect from a std::unique_pointer with special edge cases.
// AuUPtr<T, Deleter_t> - what one would expect from a std::unique_ptr<T, Deleter_t> with special superset behaviour.
//
// AuUPtr<T> - prior to 2024/09, invalid
// AuUPtr<T> - after 2024/09, an empty function callback unique pointer container. 2x void*
// - use me for maximum laziness
// after 2024/09:
// (you will probably use me, after 2024/09)
// AuUPtr<T> - prior to 2024/09, invalid. you must use AuHUPOf_t<T> instead.
// AuUPtr<T> - after 2024/09, an empty function callback unique pointer container.
// sizeof(AuUPtr<T>) == 2 * sizeof(void*)
// can be used by heap allocations or AuDefaultDeleter<T> in the same type signature.
//
// previously, AuHUPOf_t<T> would just hold heap allocations, and AuUPtr<..., AuDefaultDeleter<T>> would need
// to carry the explicit typesignature.
// in currnet era, all these use cases can fall under the exact same container under the exact same type sig.
// also note that the common signature did not break sizeof(AuUPtr<..., AuDefaultDeleter<T>>) == sizeof(void *).
//
// use me for maximum laziness.
//
// (you will probably use me with various libraries, but not create new objects yourself)
// ( Bonus: auROXTL/Objects/SOO )
// SOO - Small Object Optimization; external library allocations need not be required.
// Implemented using macros in place of templates.
// Various boxing, no copy/move, trivial copy/move, no copy, etc macro variants exist.
// Allocations can be deferred to a preferred heap ( SOO ## PtrType ## OnHeap(pHeap) )
// Allocations can be deferred to the stack using the specified SOO Type as the container typename ( SOO myObject; ).
// Will probably be an Object ((Object = SOO) ## ???) as well. All Aurora Runtime SOOs are also objects.
//
// (you will probably use me with various libraries, but not create new objects yourself)
// ( Bonus: AU_MACROS )
// Object - Allocations of AuSPtr<T> handles ( = Object ## Shared(...) ) )
// Allocations of AuUPtr<T> handles ( = Object ## GenericUnique(...) )
// Allocations of optimized AuUPtr<T, ...> handles (= Object ## Unique_t x(Object ## Unique(...)))
// Allocations of VOID* handles can be allocated using the library's default allocator,
// and then used in abstraction layers of C libraries by using the T* as generics ( = Object ## New(...) / Release() ).
// For instance consider a C library requiring threading support, one could provide myLibAllocMutex()
// using a C++ translation unit in extern "C" mode and by utilising C-style opaques & void*-sized slots.
//
// after 2024/09 ( after QOL and a replacement AuUPtr<T> container. ):
// std::shared_ptr<T> a = { AuSPtr<T>() }
// std::unique_ptr<T, ...> a = { AuUPtr<T, ...>().Release(), AuUPtr<T, ...>().GetDeleter() }
// AuUPtr<T, ...> a = { std::unique_ptr<T, ...>().release(), std::unique_ptr<T, ...>().get_deleter() }
// AuSPtr<T> a = { std::shared_ptr<T>() }
// AuSPtr<T> a = AuUnsafeRaiiToShared((T *)0) (N/A Shared Pointer)
// AuSPtr<T> a = AuUnsafeRaiiToShared(c AuUPtr<T, ...>&) (N/A Shared Pointer)
// AuHUPOf_t<T> a = AuNullHeapPointer<T>() (2x void * sized container)
// AuUPtr<T> a = AuNullHeapPointer<T>() (2x void * sized container)
// AuHUPOf_t<T> a { AuMove(AuUPtr<T>) } (2x void * sized container)
// AuUPtr<T> a { AuMove(AuHUPOf_t<T>) } (2x void * sized container)
// AuUPtr<T> a { _new Kot() } (2x void * sized container)
// AuSPtr<T> a { AuMove(a) } (N/A Shared Pointer)
// AuUPtr<T, AuDefaultDeleter<...>> a { _new Kot() } (void * sized container)
// AuHUPOf_t<T> a { } (2x void * sized container)
// AuUPtr<T> a { } (2x void * sized container)
// AuHUPOf_t<T> a = SomeAPI(...) (2x void * sized container)
@ -59,20 +99,26 @@
// AuUPtr<T> a = SOOObjectGenericUnique(...) (2x void * sized container)
// AuHUPOf_t<T> a = SOOObjectGenericUniqueOnHeap(pMyHeap, ...) (2x void * sized container)
// AuUPtr<T> a = SOOObjectGenericUniqueOnHeap(pMyHeap, ...) (2x void * sized container)
// AuUPtr<T,Deleter>|SOOOnHeapUnique_t a =
// AuUPtr<T,Deleter>|SOOObjectOnHeapUnique_t a =
// SOOObjectUniqueOnHeap(pMyHeap, ...) (void* sized container)
// AuSPtr<T> a = SOOObjectSharedOnHeap(pMyHeap) (N/A Shared Pointer)
// AuSPtr<T> a = { SOOObject myObject; myObject->X(); (N/A Shared Pointer)
// return myObject.AsUnsafeSharedPointer(); } (make sure myObject remains in scope)
// T * a = { SOOObject myObject; myObject->X(); (void*/T* sized container)
// return myObject.AsPointer(); } (make sure myObject remains in scope)
// AuUPtr<T> a = x = SOOObjectUniqueOnHeap(pMyHeap, ...) (2x void * sized container)
// return { x.Release(), x.GetDeleter().Get() };
// SOOObject...cont as FuncName
// AuUPtr<T,Deleter>|FuncNameUnique_t a = FuncNameUnique() (void* sized container)
// AuUPtr<T> a = FuncNameGenericUnique() (2x void * sized container)
// AuUPtr<T,Deleter>|FuncNameSmallUnique_t a = FuncNameUnique() (void* sized container - old behaviour, lower overhead)
// AuHPtr<T> a = FuncNameGenericUnique() (void* sized container - old behaviour, lower overhead)
// AuUPtr<T,Deleter>|FuncNameSmallUnique_t a = FuncNameUnique() (void* sized container)
// AuSPtr<T> a = FuncNameShared() (N/A Shared Pointer)
// AuHPtrs of SmallUnique's are becoming the new AuHUPOf_t<T>()
// before 2024/09:
// before 2024/09 (STL compliant. gross. very limiting. ):
// std::shared_ptr<T> a = { AuSPtr<T>() }
// AuUPtr<T, ...> a = { std::unique_ptr<T, ...>().release(), std::unique_ptr<T, ...>().get_deleter() }
// AuSPtr<T> a = { std::shared_ptr<T>() }
// AuSPtr<T> a = AuUnsafeRaiiToShared((T *)0) (N/A Shared Pointer)
// AuSPtr<T> a = AuUnsafeRaiiToShared(c AuUPtr<T, ...>&) (N/A Shared Pointer)
// AuUPtr<T, AuDefaultDeleter<...>> a { _new Kot() } (void * sized container)
// AuHUPOf_t<T> a = AuNullHeapPointer<T>() (2x void * sized container)
// AuSPtr<T> a { AuMove(a) } (N/A Shared Pointer)
@ -82,6 +128,10 @@
// AuUPtr<T, ...> a = FuncNameUnique() (void* sized container)
// AuUPtr<T,Deleter>|FuncNameUnique_t a = FuncNameUnique() (void* sized container)
// AuSPtr<T> a = FuncNameShared() (N/A Shared Pointer)
// AuSPtr<T> a = { SOOObject myObject; myObject->X(); (N/A Shared Pointer)
// return myObject.AsUnsafeSharedPointer(); } (make sure myObject remains in scope)
// T * a = { SOOObject myObject; myObject->X(); (void*/T* sized container)
// return myObject.AsPointer(); } (make sure myObject remains in scope)
// AuHPtr<T> - did not exist
// but still:
// AuHUPOf_t<T> will be kept around just in case we need to build against the spec, I suppose.