[*] Updated auMemoryAllocate.hpp *comment*

Include/auROXTL/MemoryModel/auMemoryAllocate.hpp

@@ -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.
+//                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.
+//                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
+// (you will probably use me, after 2024/09)
-// AuUPtr<T>    -  after    2024/09, an empty function callback unique pointer container. 2x void* 
+// AuUPtr<T>    -  prior to 2024/09, invalid. you must use AuHUPOf_t<T> instead.
-//              -                    use me for maximum laziness
+// AuUPtr<T>    -  after    2024/09, an empty function callback unique pointer container.
-// after 2024/09:
+//                                   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)
+//     AuUPtr<T,Deleter>|FuncNameSmallUnique_t a = FuncNameUnique()   (void* sized container)
-//     AuHPtr<T>    a = FuncNameGenericUnique()                       (void* sized container - old behaviour, lower overhead)
 //     AuSPtr<T>    a = FuncNameShared()                              (N/A Shared Pointer)
-//     AuHPtrs of SmallUnique's are becoming the new AuHUPOf_t<T>()
+// before 2024/09 (STL compliant. gross. very limiting. ):
-// before 2024/09:
 //     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.