recycling.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_containers of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace containers {
 
//==================================================================================================
/// This enumeration contains three elements, which denote the type of node-recycling that a
/// container instantiation is deemed to perform. One of these elements is to be set as the value
/// for a corresponding template parameter named \p{TRecycling} found in container types
/// of this module.
///
/// In the case \b Shared is given, the container type will expose a type definition named
/// \b SharedRecyclerType, which can be used to define the external shared recycler object.
/// This object has then to be passed to the constructor of the container instance.
///
/// \see
///   Chapter \ref alib_contmono_intro_recycling of the Programmer's Manual
///   for this \alibmod.
//==================================================================================================
enum class Recycling
{
    None   ,    ///<< Denotes that no recycling should be performed.
    Private,    ///<< Denotes private recycling. This is usaully the default value.
    Shared ,    ///<< Denotes shared recycling.
};
 
 
} // namespace alib[::containers]
 
/// Type alias in namespace \b alib.
using Recycling= containers::Recycling;
 
} // namespace [alib]
 
ALIB_EXPORT namespace alib::containers::detail {
#include "ALib.Lang.CIFunctions.H"
 
/// Stores an element for recycling.
/// @param recyclables  The recycling stack.
/// @param elem         The element to recycle.
template<typename TNode>
void    recycleImpl( lang::SidiListHook<TNode>& recyclables, TNode* elem )
{
    lang::Destruct(*elem);
    recyclables.pushFront( elem );
}
 
 
/// Stores a list of elements for recycling (from the \p{begin} element to the last one).
/// @param recyclables  The recycling stack.
/// @param begin        The first element of the list store, must not be \c nullptr.
template<typename TNode>
void    recycleListImpl( lang::SidiListHook<TNode>& recyclables, TNode* begin ) {
    TNode* actual  = begin;
    for (;;) {
        TNode* next= actual->next();
        lang::Destruct(*actual);
        if (next == nullptr)
            break;
        actual= next;
    }
 
    recyclables.pushFront( begin, actual );
}
 
/// Stores a list of elements for recycling. Both given nodes have to exist.
/// @param recyclables  The recycling stack.
/// @param begin        The first element of the list store.
/// @param end          The first element not to be recycled.
/// @return A pair of values. The first is a pointer to the last node recycled, and the second
///         provides the number of nodes recycled.
template<typename TNode>
std::pair<TNode*,integer>  recycleListImpl( lang::SidiListHook<TNode>& recyclables,
                                           TNode* begin, TNode* end ) {
    std::pair<TNode*,integer> result;
    result.second= 1;
    result.first = begin;
    for (;;) {
        TNode* next= result.first->next();
        lang::Destruct(*result.first);
        if (next == end)
            break;
        ++result.second;
        result.first= next;
    }
 
    recyclables.pushFront( begin, result.first );
    return result;
}
 
/// Reserves the given \p{qty} of recyclables. If the allocator used returns \c true with
/// method \alib{lang::Allocator;allowsMemSplit} (like like \b MonoAllocator does), then one
/// chunk is allocated and cut into pieces.<br>
/// Otherwise, common allocations are performed
/// @param allocator    The allocator to use.
/// @param recyclables  The recycling stack.
/// @param qty          The quantity of elements to reserve.
template<typename TAllocator, typename TNode>
void    reserveImpl( TAllocator& allocator, lang::SidiListHook<TNode>& recyclables, integer qty ) {
    if (qty <= 0)
        return;
 
    if constexpr ( TAllocator::allowsMemSplit() ) {
        TNode* newElements= allocator().template AllocArray<TNode>(qty);
        for( integer i= qty - 2; i >= 0   ; --i )
            newElements[i].next( &newElements[i + 1] );
 
        recyclables.pushFront( &newElements[0], &newElements[qty-1] );
    } else {
        TNode* start= allocator().template Alloc<TNode>();
        TNode* end = start;
        for( integer i= 1; i < qty   ; ++i ) {
            end->next( allocator().template Alloc<TNode>() );
            end= end->next();
        }
        recyclables.pushFront( start, end );
}   }
 
/// Frees an element (no recycling).
/// @param allocator  The allocator to use.
/// @param elem         The element to recycle.
template<typename TAllocator, typename TNode>
void    disposeImpl( TAllocator& allocator, TNode* elem )
{
    lang::Destruct(*elem);
    allocator().Free(elem);
}
 
 
/// Deletes the given list.
/// This shared recycler does not free the node, but recycles them.
/// @param allocator  The allocator to use.
/// @param begin      The first element of the list to free.
template<typename TAllocator, typename TNode>
void disposeListImpl( TAllocator& allocator, TNode* begin ) {
    TNode* actual  = begin;
    for (;;) {
        TNode* next= actual->next();
        lang::Destruct(*actual);
        allocator().Free(actual);
        if (next == nullptr)
            return;
        actual= next;
}   }
 
/// Deletes a list of elements for recycling. Both given nodes have to exist.
/// @param allocator  The allocator to use.
/// @param begin      The first element of the list to free.
/// @param end        The first element not to be freed.
/// @return A pair of values. The first is a pointer to the last node deleted, and the second
///         provides the number of nodes deleted.
template<typename TAllocator, typename TNode>
std::pair<TNode*,integer>    disposeListImpl( TAllocator& allocator,  TNode* begin, TNode* end ) {
    std::pair<TNode*,integer> result;
    result.second= 1;
    result.first= begin;
    for (;;) {
        TNode* next= result.first->next();
        lang::Destruct(*result.first);
        allocator().Free(result.first);
        if (next == end)
            return result;
        ++result.second;
        result.first= next;
}   }
 
/// Recycles a chunk of memory that is \e not of the node type.
/// Such recycling is useful for example, in combination with hash tables, which usually
/// allocate a "bucket array" that grows over time. In this case, the former smaller bucket
/// array may be passed to this method to recycle it as future node elements.
/// @tparam TChunk      The type of the external chunk.
/// @param  recyclables The recycling stack.
/// @param  chunk       The recyclable chunk's address.
/// @param  count       The number of objects. (For non-array types, \c 1 is to be given.)
template<typename TNode, typename TChunk>
void    recycleChunkImpl( lang::SidiListHook<TNode>& recyclables, TChunk* chunk, size_t count ) {
    void*   mem = chunk;
    size_t  size= sizeof(TChunk[1]) * count;
 
    // align beginning of buffer (if necessary)
    if constexpr( alignof(TNode) > alignof(TChunk[1])  ) {
        mem =  reinterpret_cast<void*>((size_t(chunk) + alignof(TNode) - 1) & ~(alignof(TNode) -1));
        size-= size_t(reinterpret_cast<char*>(mem) - reinterpret_cast<char*>(chunk));
    }
 
    // create recyclables
    ALIB_DBG( size_t cntRecycledObjects= 0; )
    while(size > sizeof(TNode)) {
        recyclables.pushFront( reinterpret_cast<TNode*>( mem ) );
        mem  =  reinterpret_cast<char*>(mem) + sizeof(TNode);
        size -= sizeof (TNode);
        ALIB_DBG( ++cntRecycledObjects; )
    }
 
    #if ALIB_DEBUG
        if( cntRecycledObjects <= 0 ) {
            ALIB_WARNING( "MONOMEM/RECYCLER",
              "De-allocated chunk size is smaller than node size.\n"
              "  Chunk object:       Type: <{}>\n"
              "    Size, Count, Alignment: {} * {} = {} bytes, alignment: {}\n"
              "           Recyclable Type: <{}>\n"
              "           Size, Alignment: {} bytes, alignment: {}\n"
              "Note: If this recycler is used with a <containers::HashTable>, this message may be\n"
              "      eliminated by reserving a reasonable initial bucket size.",
              &typeid(TChunk), sizeof(TChunk[1]), count, sizeof(TChunk[1]) * count,
              alignof(TChunk[1]), &typeid(TNode), sizeof(TNode), alignof(TNode)  )
        }
    #endif
}
 
#include "ALib.Lang.CIMethods.H"
 
/// Implements internal recycling interface. Used by container types of module \alib_containers_nl that
/// use private recycling (when \b their template parameter \p{TRecycling} evaluates to
/// \alib{containers;Recycling;Private}).
///
/// @tparam TAllocator The allocator to store and use.
/// @tparam TNode      The type to recycle. Has to be derived of \alib{lang::SidiNodeBase}.
template<typename TAllocator, typename TNode>
struct RecyclerPrivate  : lang::AllocatorMember<TAllocator>
{
  protected:
        /// The base type.
        using base= lang::AllocatorMember<TAllocator>;
 
    /// The list of recyclables.
    lang::SidiListHook<TNode>  recyclables;
 
  public:
    /// Parameterless constructor. Used with type \b HeapAllocator.
    RecyclerPrivate()                                                             noexcept =default;
 
    /// Constructor taking an allocator.
    /// @param pAllocator The allocator to use.
    explicit
    RecyclerPrivate( TAllocator& pAllocator )                                               noexcept
    : base( pAllocator )                                                                          {}
 
    /// Copy constructor. Does not copy the recycle node, but clears this one.
    /// @param copy The object to copy.
    RecyclerPrivate( const RecyclerPrivate& copy )                                          noexcept
    : base( copy )                                                                                {}
 
    /// Move constructor. Grabs the recyclables from the moved one and sets moved to nulled.
    /// @param move The private recycler to move.
    RecyclerPrivate( RecyclerPrivate&& move )                                               noexcept
    : base( move )
    , recyclables(move)                                                { move.recyclables.reset(); }
 
    /// Destructor. Frees all recyclables with the allocator.
    ~RecyclerPrivate()                                                                    noexcept {
        TNode* actual  = recyclables.first();
        while (actual) {
            TNode* next= actual->next();
            base::AI().Free(actual);
            actual= next;
    }   }
 
    /// Resets this recycler. Frees all recyclables with the allocator.
    void Reset()                                                                          noexcept {
        if(recyclables.first()) {
            disposeListImpl(base::GetAllocator(), recyclables.first());
            recyclables.reset();
    }   }
 
    /// @return Returns the allocator received with construction.
    TAllocator&  GetAllocator()                      const noexcept { return base::GetAllocator(); }
 
    /// @return The allocator interface of the allocator received with construction.
    lang::AllocatorInterface<TAllocator> AI()      const noexcept { return base::GetAllocator()(); }
 
    /// @return Returns \c true to indicate that this is not a non-recycling version.
    static constexpr bool IsRecycling()                                    noexcept { return true; }
 
    /// Counts the number of recyclables.<br>
    /// Attention: This method runs in linear time.
    /// @return The number of available elements.
    [[nodiscard]]
    integer       Count()                             const noexcept { return recyclables.count(); }
 
 
    /// Reserves the given number of recyclables.
    /// @param qty  The number of new recyclables to allocate.
    void Reserve( integer qty )   noexcept { reserveImpl( base::GetAllocator(), recyclables, qty); }
 
    /// Returns a recycled object or allocates a new one.
    /// @return A recycled or allocated element.
    [[nodiscard]]
    TNode*        Get() {
        return  !recyclables.isEmpty() ? recyclables.popFront()
                                       : base::AI().template Alloc<TNode>();
    }
 
    /// Stores an element for recycling.
    /// @param elem The element to store.
    void Recycle( TNode* elem )                       noexcept { recycleImpl( recyclables, elem ); }
 
    /// Stores a list of elements for recycling (from the \p{begin} element to the last one).
    /// @param begin The first element of the list store, must not be \c nullptr.
    void RecycleList( TNode* begin )             noexcept { recycleListImpl( recyclables, begin ); }
 
    /// Stores a list of elements for recycling. Both given nodes have to exist.
    /// @param begin The first element of the list to recycle.
    /// @param end   The first element not to be recycled.
    /// @return A pair of values. The first is a pointer to the last node recycled, and the second
    ///         provides the number of nodes recycled.
    std::pair<TNode*, integer> RecycleList(TNode* begin, TNode* end)                        noexcept
    { return recycleListImpl( recyclables, begin, end ); }
 
    /// Deletes the given list.
    /// This shared recycler does not free the node, but recycles them.
    /// @param begin The first element of the list to free.
    void DisposeList( TNode* begin )    noexcept { disposeListImpl( base::GetAllocator(), begin ); }
 
    /// Deletes a list of elements for recycling. Both given nodes have to exist.
    /// @param begin The first element of the list to free.
    /// @param end   The first element not to be freed.
    void DisposeList( TNode* begin, TNode* end )                                            noexcept
    { disposeListImpl( base::GetAllocator(), begin, end ); }
 
 
    /// Converts a given chunk of memory, previously allocated with the same allocator that
    /// this type uses, into recyclable node objects.<br>
    /// This is only done if \alib{lang;Allocator::allowsMemSplit} returns \c true.
    /// @tparam TChunk The type of array that is to be cut into node elements.
    /// @param chunk   The chunk array to convert into nodes
    /// @param length  The length of the chunk array (pass \c 1 if the chunk is not an array type).
    template<typename TChunk>
    void RecycleChunk(TChunk* chunk, size_t length )                                      noexcept {
        if constexpr ( TAllocator::allowsMemSplit() )
            recycleChunkImpl( recyclables, chunk, length );
        else
            #if !defined(__MINGW32__)
                base::AI().FreeArray(chunk, length );
            #else
                base::AI().template FreeArray(chunk, length );
            #endif
    }
 
    /// Frees the given memory. Note that the shared recycler calls #RecycleChunk with this method.
    /// @tparam TChunk The type of array that is to be freed.
    /// @param chunk   The chunk array to convert into nodes
    /// @param length  The length of the chunk array (pass \c 1 if the chunk is not an array type).
    template<typename TChunk>
    void DisposeChunk(TChunk* chunk, size_t length )                                      noexcept {
        #if !defined(__MINGW32__)
            base::AI().FreeArray(chunk, length );
        #else
            base::AI().template FreeArray(chunk, length );
        #endif
    }
};
 
/// This is the type exposed to users of the \alib containers in case shared recycling is
/// chosen, for example, with \alib{containers;List::SharedRecyclerType} or
/// \alib{containers;HashTable::SharedRecyclerType}.<br>
/// A user has to pass an instance of this type to the constructor of the container.
/// Constructors that accept this type do not accept an allocator instance, as this is embedded
/// already here.
/// @tparam TAllocator The allocator to store and use.
/// @tparam TNode      The node type to recycle.
template<typename TAllocator, typename TNode>
class SharedRecycler  : public    lang::AllocatorMember<TAllocator>
                      , protected lang::SidiListHook<TNode>
{
  protected:
    template<typename TAllocator1, typename TNode1>
    friend class RecyclerShared;
 
    /// Shortcut to a base class.
    using allocBase=   lang::AllocatorMember<TAllocator>;
 
    /// Shortcut to a base class.
    using hookBase=    lang::SidiListHook<TNode>;
 
 
  public:
    /// Constructor taking no allocator, used with \b %HeapAllocator.
    SharedRecycler ()                                                                       noexcept
    : lang::AllocatorMember<TAllocator>()                                                         {}
 
    /// Constructor taking an allocator.
    /// @param pAllocator The allocator to use.
    SharedRecycler ( TAllocator& pAllocator )                                               noexcept
    : allocBase( pAllocator )                                                                     {}
 
    /// Destructor. Deletes all recyclables with the allocator.
    ~SharedRecycler()                                                          noexcept { Reset(); }
 
    /// Reset. Deletes all recyclables with the allocator.
    void Reset()                                                                          noexcept {
        TNode* actual  = this->first();
        while (actual) {
            TNode* next= actual->next();
            allocBase::AI().Free(actual);
            actual= next;
        }
        this->reset();
    }
 
    /// Counts the number of recyclables.
    /// @return The number of recycled container elements available.
    integer Count()                                         const noexcept { return this->count(); }
 
    /// Reserves space for at least the given number of recyclables.
    /// @param qty       The expected number or increase of elements to be stored in the containers
    ///                  that share this recycler.
    /// @param reference Denotes whether \p{expected} is meant as an absolute size or an increase .
    void Reserve( integer qty, lang::ValueReference reference ) {
        auto requiredRecyclables= ( qty - (reference == lang::ValueReference::Absolute ? Count()
                                                                                       : 0     ) );
 
        if( requiredRecyclables > 0 )
            reserveImpl( allocBase::GetAllocator(), *this, requiredRecyclables );
    }
};
 
/// Implements internal recycling interface. Used by container types of module \alib_containers_nl that
/// use shared recycling (when \b their template parameter \p{TRecycling} evaluates to
/// \alib{containers;Recycling;Shared}).
///
/// @tparam TAllocator The allocator to store and use.
/// @tparam TNode      The type to recycle. Has to be derived of \alib{lang::SidiNodeBase}.
template<typename TAllocator, typename TNode>
class RecyclerShared
{
  protected:
    /// The reference to the list of recyclables.
    SharedRecycler<TAllocator,TNode>&  sr;
 
  public:
 
    /// Constructor taking an allocator and the hook.
    /// @param hook       The external, shared recycling list.
    RecyclerShared ( SharedRecycler<TAllocator,TNode>& hook )                               noexcept
    : sr(hook)                                                                                    {}
 
 
    /// Copy constructor. Copies the reference to the shared recycler.
    /// @param copy The private recycler to copy.
    RecyclerShared( const RecyclerShared& copy )                                  noexcept =default;
 
    /// Move constructor. Just copies the reference but leaves original intact. (We don't care)
    /// @param move The private recycler to move.
    RecyclerShared( RecyclerShared&& move )                                                 noexcept
    : sr(move.sr)                                                                                 {}
 
    /// Destructor.
    ~RecyclerShared()                                                                    noexcept {}
 
    /// Does nothing. Shared recyclers can't be reset.
    void Reset()                                                                         noexcept {}
 
    /// @return Returns the allocator received with construction.
    TAllocator&  GetAllocator()                         const noexcept { return sr.GetAllocator(); }
 
    /// @return The allocator interface of the allocator received with construction.
    lang::AllocatorInterface<TAllocator> AI()         const noexcept { return sr.GetAllocator()(); }
 
 
    /// @return Returns \c true to indicate that this is not a non-recycling version.
    static constexpr bool IsRecycling()                                    noexcept { return true; }
 
    /// Counts the number of recyclables.<br>
    /// Attention: This method runs in linear time.
    /// @return The number of available elements.
    [[nodiscard]]
    integer       Count()                                      const noexcept { return sr.count(); }
 
    /// Reserves the given number of recyclables.
    /// @param qty  The number of new recyclables to allocate.
    void Reserve( integer qty )                        { reserveImpl( sr.GetAllocator(), sr, qty); }
 
    /// Returns a recycled object or allocates a new one.
    /// @return A recycled or allocated element.
    [[nodiscard]]
    TNode*        Get()  { return !sr.isEmpty() ? sr.popFront() : sr.AI().template Alloc<TNode>(); }
 
    /// Stores an element for recycling.
    /// @param elem The element to store.
    void Recycle( TNode* elem )                                noexcept { recycleImpl( sr, elem ); }
 
    /// Stores a list of elements for recycling (from the \p{begin} element to the last one).
    /// @param begin The first element of the list store, must not be \c nullptr.
    void RecycleList( TNode* begin )                      noexcept { recycleListImpl( sr, begin ); }
 
    /// Stores a list of elements for recycling. Both given nodes have to exist.
    /// @param begin The first element of the list to recycle.
    /// @param end   The first element not to be recycled.
    /// @return A pair of values. The first is a pointer to the last node recycled, and the second
    ///         provides the number of nodes recycled.
    std::pair<TNode*, integer>  RecycleList(TNode* begin, TNode* end)                       noexcept
    { return recycleListImpl( sr, begin, end ); }
 
    /// Does not free, but recycles instead.
    /// @param begin The first element of the list to free.
    void DisposeList( TNode* begin )                      noexcept { recycleListImpl( sr, begin ); }
 
    /// Does not free, but recycles instead.
    /// @param begin The first element of the list to free.
    /// @param end   The first element not to be freed.
    void DisposeList( TNode* begin, TNode* end )     noexcept { recycleListImpl( sr, begin, end ); }
 
    /// Converts a given chunk of memory, previously allocated with the same allocator that
    /// this type uses, into recyclable node objects.<br>
    /// This is only done if \alib{lang;Allocator::allowsMemSplit} returns \c true.
    /// @tparam TChunk The type of array that is to be cut into node elements.
    /// @param chunk   The chunk array to convert into nodes
    /// @param length  The length of the chunk array (pass \c 1 if the chunk is not an array type).
    template<typename TChunk>
    void RecycleChunk(TChunk* chunk, size_t length )                                      noexcept {
        if constexpr ( TAllocator::allowsMemSplit() )
            recycleChunkImpl( sr, chunk, length );
        else
            sr.AI().FreeArray(chunk, length );
    }
 
    /// This shared recycler calls #RecycleChunk with this method.
    /// @tparam TChunk The type of array that is to be freed.
    /// @param chunk   The chunk array to convert into nodes
    /// @param length  The length of the chunk array (pass \c 1 if the chunk is not an array type).
    template<typename TChunk>
    void DisposeChunk(TChunk* chunk, size_t length )     noexcept { RecycleChunk( chunk, length ); }
};
 
 
/// Implements internal recycling interface. Used by container types of module \alib_containers_nl
/// that omit recycling (when \b their template parameter \p{TRecycling} evaluates to
/// \alib{containers;Recycling;None}).
///
/// @tparam TAllocator The allocator to store and use.
/// @tparam TNode      The type to recycle. Has to be derived of \alib{lang::SidiNodeBase}.
template<typename TAllocator, typename TNode>
struct RecyclerVoid  : lang::AllocatorMember<TAllocator>
{
  protected:
    /// The base type.
    using base= lang::AllocatorMember<TAllocator>;
 
  public:
    /// Parameterless constructor. Used with type \b HeapAllocator.
    RecyclerVoid() : base()                                                                       {}
 
    /// Defaulted default constructor.
    /// @param pAllocator The allocator to use.
    RecyclerVoid( TAllocator& pAllocator )                                                  noexcept
    : base( pAllocator )                                                                          {}
 
    /// Does nothing. Shared recyclers can't be reset.
    void Reset()                                                                         noexcept {}
 
    /// @return Returns \c false to indicate that this is a non-recycling version.
    static constexpr bool   IsRecycling()                                 noexcept { return false; }
 
    /// This recycler just returns \c 0.
    /// Attention: With other implementations, this method may run in linear time.
    /// @return \c 0, which in this case is always the number of available elements.
    [[nodiscard]]
    constexpr integer       Count()                                     const noexcept { return 0; }
 
    /// Does nothing. In debug-compilations a \ref alib_mod_assert "warning is raised".
    void    Reserve( integer )                                                              noexcept
    { ALIB_WARNING("MONOMEM","Requested reservation of recyclables with non-recycling container.") }
 
    /// Allocates a new one.
    /// @return An allocated element.
    [[nodiscard]]
    TNode*  Get()                                     { return base::AI().template Alloc<TNode>(); }
 
    /// Frees an element.
    /// @param elem The element to store.
    void    Recycle( TNode* elem )           noexcept { disposeImpl( base::GetAllocator(), elem ); }
 
    /// Frees the list.
    /// @param begin The first element of the list store, must not be \c nullptr.
    void    RecycleList( TNode* begin ) noexcept { disposeListImpl( base::GetAllocator(), begin ); }
 
    /// Frees the list (as this is a non-recycling recycler).
    /// @param begin The first element of the list recycled.
    /// @param end   The first element not to be recycled.
    /// @return A pair of values. The first is a pointer to the last node deleted, and the second
    ///         provides the number of nodes deleted.
    std::pair<TNode*, integer>      RecycleList( TNode* begin, TNode* end )                 noexcept
    { return disposeListImpl( base::GetAllocator(), begin, end ); }
 
 
    /// Deletes a list of elements (from the \p{begin} element to the last one).
    /// @param begin The first element of the list recycle, must not be \c nullptr.
    void    DisposeList( TNode* begin ) noexcept { disposeListImpl( base::GetAllocator(), begin ); }
 
    /// Deletes a list of elements for recycling. Both given nodes have to exist.
    /// @param begin The first element of the list to free.
    /// @param end   The first element not to be freed.
    /// @return A pair of values. The first is a pointer to the last node deleted, and the second
    ///         provides the number of nodes deleted.
    std::pair<TNode*, integer>      DisposeList( TNode* begin, TNode* end )                 noexcept
    { return disposeListImpl( base::GetAllocator(), begin, end ); }
 
    /// With other recyclers, this method
    /// converts a given chunk of memory, previously allocated with the same allocator that
    /// this type uses, into recyclable node objects.<br>
    /// This recycler just frees the object.
    /// @tparam TChunk The type of array that is to be cut into node elements.
    /// @param chunk  The chunk array to convert into nodes
    /// @param length The length of the chunk array (pass \c 1 if the chunk is not an array type).
    template<typename TChunk>
    constexpr void          RecycleChunk( TChunk* chunk, size_t length )                  noexcept {
        #if !defined(__MINGW32__)
            base::AI().FreeArray(chunk, length );
        #else
            base::AI().template FreeArray(chunk, length );
        #endif
    }
 
    /// Frees the given memory. Note that the shared recycler calls #RecycleChunk with this method.
    /// @tparam TChunk The type of array that is to be freed.
    /// @param chunk   The chunk array to convert into nodes
    /// @param length  The length of the chunk array (pass \c 1 if the chunk is not an array type).
    template<typename TChunk>
    void DisposeChunk(TChunk* chunk, size_t length )                                      noexcept {
        #if !defined(__MINGW32__)
            base::AI().FreeArray(chunk, length );
        #else
            base::AI().template FreeArray(chunk, length );
        #endif
    }
 
}; // struct RecyclerVoid
 
/// Helper-struct that chooses the right recycler type depending on template parameter
/// \p{TRecycling}. Specializations exists for each element in enumeration
/// \alib{containers;Recycling}.
/// @tparam TRecycling The sort of recycling, as given with template parameter of container types
///                    with the same name.
template<Recycling TRecycling>
struct RecyclingSelector
{
    #if DOXYGEN
    /// The type chosen.
    using Type= void;
 
    /// The hook type. Only used with shared recycling, otherwise <c>void</c>.
    using HookType= void;
    #endif
};
#if !DOXYGEN
template<>
struct RecyclingSelector<Recycling::Private>
{
    template<typename TAllocator, typename TNode>    using Type= RecyclerPrivate<TAllocator, TNode>;
    template<typename TAllocator, typename TNode>    using HookType= void;
};
 
template<> struct RecyclingSelector<Recycling::Shared>
{
    template<typename TAllocator, typename TNode>   using Type    = RecyclerShared<TAllocator, TNode>;
    template<typename TAllocator, typename TNode>   using HookType= SharedRecycler<TAllocator, TNode>;
};
 
template<> struct RecyclingSelector<Recycling::None>
{
    template<typename TAllocator, typename TNode>  using Type= RecyclerVoid<TAllocator, TNode>;
    template<typename TAllocator, typename TNode>  using HookType= void;
};
#endif
 
#include "ALib.Lang.CIMethods.H"
} // namespace [alib::containers::detail]