dbgboxing.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header file is part of module \alib_boxing of the \aliblong.
///
/// \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_ALIB_BOXING_DBGBOXING
#define HPP_ALIB_BOXING_DBGBOXING 1
#pragma once
#include "alib/boxing/boxing.hpp"
 
#if ALIB_DEBUG_BOXING
 
#if ALIB_CAMP
#   include "alib/lang/format/formatter.hpp"
#endif
 
#include <tuple>
 
namespace alib {  namespace boxing {
 
 
#if ALIB_CAMP
namespace detail {
//==================================================================================================
/// Template class implementing a monotonically allocated vector of variadic tuples whose first
/// element is of type \alib{strings;TString<TChar>;String}.
///
/// When new tuples are added with the method #Add, then memory for copying the provided string is
/// allocated using an internal field of type \alib{MonoAllocator}.
/// This allows adding single strings, which are allocated in bigger memory buffers.
///
/// Standard vector operations, including insertions and deletions are still allowed.
/// In other words, it is allowed to store string objects which are pointing to string data that
/// is \b not allocated in the internal buffers.
///
/// The associated values are especially useful when the vector is sorted (e.g., using
/// \c std::sort), because such associations will be kept intact and allow referencing back
/// to whatever the strings represents.
///
/// \par Availability
///   This struct is only available if compiler symbol \ref ALIB_DEBUG_BOXING is set and
///   furthermore, module \alib_basecamp is included in the \alibdist.
//==================================================================================================
template< typename... TAssociatedTypes >
struct DbgStringTable  : public std::vector<std::tuple<String, TAssociatedTypes...>>
{
   /// Shortcut to the <c>std::tuple</c>-type that instantiations of this template class store.
   using ElementType= std::tuple<String, TAssociatedTypes...>;
 
   /// Shortcut to the base type of this type.
   using Base       = std::vector<ElementType>;
 
   /// Allocator for making copies of inserted strings
   MonoAllocator&   allocator;
 
   /// Constructor.
   /// @param monoAllocator   A mono allocator used to create copies of the inserted strings
   DbgStringTable( MonoAllocator&  monoAllocator )
   : allocator(monoAllocator)
   {}
 
   /// Adds a tuple. The contents of the string of the tuple (its first element) is copied
   /// from the given string \p{src}. The memory for this string is allocated using
   /// the allocator provided in the constructor.<br>
   /// The other members of the tuple added are forwarded from variadic parameter block \p{args}.
   ///
   /// @param src   The string to copy into the first member of the tuple.
   /// @param args  Variadic arguments to fill the rest of the inserted tuple.
   ///
   /// @return A reference to the string that was added.
   template <typename... TArgs>
   String& Add( const String& src, TArgs&&... args )
   {
       // on errors, see note above!
       Base::emplace_back( String(allocator, src), std::forward<TArgs>(args)... );
       return std::get<0>( std::vector<std::tuple<String, TAssociatedTypes...>>::back() );
   }
};
} // namespace detail
 
#endif // ALIB_CAMP
 
 
 
//==================================================================================================
/// Provides low- and high-level debug methods for \alib_boxing_nl.<br>
///
/// This type is not constructible, as all method are static.
///
/// To shorten custom type names, custom namespaces might be added to static vector
/// #RemovableNamespaces before invoking a method.
///
/// \note
///   While some of the methods are written with a non-capital letter (which usually indicates
///   that they are \c protected or \c private), those are still declared \c public. These methods
///   are "inner" methods used by the similar named capitalized methods.
///   Their use is recommended, when writing custom "composite" debug-functions, as the various
///   output parameters might be reused with subsequent invocations.
///
/// \par Availability
///  This struct is only available if compiler symbol \ref ALIB_DEBUG_BOXING is set.
///
/// \par
///   The following methods are available independent of the \alibdist.
///   - #GetKnownVTables
///   - #GetKnownFunctionTypes
///   - #GetSpecificFunctionTypes
///   - #getFunctionTypes
/// \par
///   The following methods become available if module \alib_strings is included in the \alibdist:
///   - #TypeName
///   - #typeName
///   - #removeNamespaces
///
/// \par
///   All other methods become available if module \alib_basecamp is included in the \alibdist.
///
/// \see
///   Chapter \ref alib_boxing_more_debug of the
///   \ref alib_mod_boxing "Programmer's Manual" of module \alib_boxing_nl.
//==================================================================================================
struct DbgBoxing
{
    //==============================================================================================
    /// Not constructible
    //==============================================================================================
    DbgBoxing() = delete;
 
    // #############################################################################################
    // Function Lists
    // #############################################################################################
 
    //==============================================================================================
    /// Returns all \e vtable singletons that have been created during program execution so far.
    /// One \e vtable is created for each mapped type used.
    ///
    /// \see
    ///   The result can be conveniently passed to #DumpVTables.
    /// @return A vector of pointers to objects of type \alib{boxing;detail::VTable}.
    //==============================================================================================
    ALIB_API static
    std::vector<detail::VTable*>
    GetKnownVTables();
 
    //==============================================================================================
    /// Returns a vector of \c std::type_info objects, representing all function types that either
    /// a default or a type specific implementation has been registered for.<br>
    /// A second value in the vector provides the number of invocations of a default implementation.
    /// If such is not available, this number is set to <c>std::numeric_limits<uinteger>::max()</c>.
    ///
    /// The list includes the built-in function types.
    ///
    /// \see
    ///   The result can be conveniently passed to #DumpFunctions.
    /// @return A vector of pairs of type information structs and usage numbers.
    //==============================================================================================
    ALIB_API static
    std::vector<std::pair<const std::type_info*,uinteger>>
    GetKnownFunctionTypes();
 
    //==============================================================================================
    /// Collects all function declarator types of the given box-function table.
    ///
    /// \see
    ///   The result can be conveniently passed to #DumpFunctions.
    ///
    /// @param input  The function table to use.
    /// @param output The result vector to fill.
    //==============================================================================================
    ALIB_API static
    void getFunctionTypes( const detail::FunctionTable&                             input,
                           std::vector<std::pair<const std::type_info*,uinteger>>&  output  );
 
    //==============================================================================================
    /// Collects all function declarator types, with type-specific implementations.
    /// Parameter \p{vtable} might for example be retrieved from a box instance with
    /// \alib{boxing;Box::DbgGetVTable}.
    ///
    /// \see
    ///   The result can be conveniently passed to #DumpFunctions.
    /// @param vtable The vtable to get all function implementations for.
    /// @return A vector of type information structs.
    //==============================================================================================
    static
    std::vector<std::pair<const std::type_info*,uinteger>>
    GetSpecificFunctionTypes( const detail::VTable* vtable )
    {
        std::vector<std::pair<const std::type_info*,uinteger>> result;
        getFunctionTypes( vtable->Functions, result );
        return result;
    }
 
    //==============================================================================================
    /// Convenience function: invokes #GetSpecificFunctionTypes(const detail::VTable*) with
    /// the \e vtable of the box created or passed with the invocation.
    ///
    /// \see
    ///   The result can be conveniently passed to #DumpFunctions.
    ///
    /// @param box  A box that the vtable is used of.
    /// @return A vector of type information structs.
    //==============================================================================================
    static
    std::vector<std::pair<const std::type_info*,uinteger>>
    GetSpecificFunctionTypes( const Box& box )
    {
        return  GetSpecificFunctionTypes( box.DbgGetVTable() );
    }
 
#if ALIB_STRINGS
    // #############################################################################################
    // Type Name
    // #############################################################################################
    //==============================================================================================
    /// Writes the (demangled) mapped type that the given \p{vtable} represents.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_strings is included in the \alibdist.
    ///
    /// @param  vtable           The \e vtable to get the mapped type name for.
    /// @return A string containing the requested information.
    //==============================================================================================
    static
    AString      TypeName  ( const detail::VTable* vtable )
    {
        AString result;
        typeName( vtable, result );
        return result;
    }
 
    //==============================================================================================
    /// Convenience function: invokes #TypeName(const detail::VTable*) with
    /// the \e vtable of the box created or passed with the invocation.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_strings is included in the \alibdist.
    ///
    /// @param  box              The box to get the mapped type name for.
    /// @return A string containing the requested information.
    //==============================================================================================
    static
    AString      TypeName  ( const Box& box )
    {
        AString result;
        typeName( box.DbgGetVTable(), result );
        return result;
    }
 
 
    //==============================================================================================
    /// Implementation of #TypeName.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_strings is included in the \alibdist.
    ///
    /// @param      vtable           The vtable.
    /// @param[out] result           The target string to write the type information to.
    //==============================================================================================
    ALIB_API static
    void         typeName  ( const detail::VTable* vtable, AString& result );
 
#endif // ALIB_STRINGS
 
#if ALIB_CAMP
#include "alib/lang/callerinfo_functions.hpp"
    // #############################################################################################
    // Type Info
    // #############################################################################################
    //==============================================================================================
    /// Returns human-readable information about the type \p{TBoxable} in respect to how boxing
    /// objects of this type is performed.
    ///
    /// The implementation of this method creates a default value of \p{TBoxable}, boxes this
    /// and returns the result of #TypeInfo(const Box&,const String&,const String&).
    /// Hence, for types that are not default constructible, inner function \b %TypeInfo
    /// has to be used with an accordingly boxed "sample" of type \p{TBoxable}
    ///
    /// \note
    ///   Does not work for type \c void*, which is not customizable anyhow
    ///   (always boxed as \c void*).
    ///
    ///
    /// \par Availability
    ///   This method is included only if module \alib_strings is included in the \alibdist.
    ///
    /// @tparam TBoxable The boxable type to investigate in.
    /// @param  headline The headline to write.
    /// @param  indent   Spaces to write before each entry.
    /// @return A string containing the requested information.
    //==============================================================================================
    template<typename TBoxable>
    static
    AString  TypeInfo( const String& headline        = A_CHAR( "Boxing Information For Boxable Type: ") ,
                       const String& indent          = A_CHAR( "  "                                   )   )
 
    {
        return DbgBoxing::TypeInfo<TBoxable>( TBoxable(), headline, indent );
    }
 
    //==============================================================================================
    /// Collects necessary information from template type \p{TBoxable} and invokes
    /// #typeInfo.<br>
    /// See method #TypeInfo.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_strings is included in the \alibdist.
    ///
    /// @tparam TBoxable The boxable type to investigate in.
    /// @param  box      A box containing a "sample" of \p{TBoxable.}. If a different box is given
    ///                  this method has undefined behavior
    /// @param  headline The headline to write.
    /// @param  indent   Spaces to write before each entry.
    /// @return A string containing the requested information.
    //==============================================================================================
    template<typename TBoxable>
    static
    AString  TypeInfo( const Box& box,
                       const String& headline= A_CHAR("Boxing Information For Boxable Type: "),
                       const String& indent  = A_CHAR("  "                                   ) )
    {
        AString target;
        using TSrc  = ATMP_RCV(TBoxable);
        using TPlain= ATMP_RCVP(TBoxable);
 
        lang::DbgTypeDemangler srcRTTIDmgld( typeid(TSrc) );
 
        // repeat twice to get auto-tabs adjusted
        ALIB_LOCK_RECURSIVE_WITH(Formatter::DefaultLock)
        Formatter& formatter= *Formatter::Default;
        formatter.Reset();
        for( int theSakeOfAutoTabs= 0 ; theSakeOfAutoTabs < 2 ; ++theSakeOfAutoTabs )
        {
            NString512 demangled;
            srcRTTIDmgld.GetShort(demangled);
            target.Reset() << headline << demangled  << NEW_LINE;
            removeNamespaces( target, headline.Length() );
 
            if( ATMP_EQ(TSrc, std::nullptr_t ) )
            {
                target  << indent << "'std::nullptr_t' sets a box to void state" << NEW_LINE;
                return target;
            }
 
            typeInfo( target,
                      box.DbgGetVTable(),
                      indent,
                      ATMP_IS_PTR(TSrc),
                      boxing::TT_IsCustomized<TPlain >::value,
                      boxing::TT_IsCustomized<TPlain*>::value,
                      sizeof(boxing::Placeholder) <= sizeof(ATMP_RCVP(TPlain)),
                      std::is_copy_constructible<ATMP_RCVP(TPlain)>::value,
                      std::is_trivially_destructible<ATMP_RCVP(TPlain)>::value,
                      boxing::TT_IsUnboxable <TSrc   >::value                             );
 
        }
        return target;
    }
 
    //==============================================================================================
    /// See method #TypeInfo, which invokes this method using template parameter \p{TBoxable}
    ///
    /// \par Availability
    ///   This method is included only if module \alib_strings is included in the \alibdist.
    ///
    /// @param[out] target                   The target string.
    /// @param      vtable                   The vtable of the mapped type.
    /// @param      indent                   Empty or a string of spaces that are alwys preprended
    ///                                      before each entry.
    /// @param      srcIsPointer             Denotes if \p{TBoxable} is a pointer type.
    /// @param      isValueTypeCustomized    Denotes if the value type of \p{TBoxable} is customized.
    /// @param      isPointerTypeCustomized  Denotes if the pointer type of \p{TBoxable} is
    ///                                      customized.
    /// @param      fitsToPlaceholder        Denotes if the value type of \p{TBoxable} would fit to
    ///                                      placeholder.
    /// @param      copyConstructible        Denotes if the value type of \p{TBoxable} is
    ///                                      copy constructible.
    /// @param      triviallyDestructible    Denotes if the value type of \p{TBoxable} is
    ///                                      trivially destructible.
    /// @param      isUnboxable              Denotes if \p{TBoxable} is unboxable.
    //==============================================================================================
    ALIB_API static
    void            typeInfo( AString&                 target,
                              const detail::VTable*    vtable,
                              const String&            indent,
                              bool                     srcIsPointer,
                              bool                     isValueTypeCustomized,
                              bool                     isPointerTypeCustomized,
                              bool                     fitsToPlaceholder,
                              bool                     copyConstructible,
                              bool                     triviallyDestructible,
                              bool                     isUnboxable                         );
 
    // #############################################################################################
    // Dump
    // #############################################################################################
    //==============================================================================================
    /// Takes a vector of pairs of \c std::type_info pointers and a usage counter and returns an
    /// \b AString with a sorted list of type names, including their counter information.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_basecamp is included in the \alibdist.
    ///
    /// @param input             A list of types.
    /// @param headline          The headline to write.
    /// @param indent            Spaces to write before each entry.
    /// @return A list of demangled type names.
    //==============================================================================================
    ALIB_API static
    alib::AString  DumpFunctions(
           const std::vector<std::pair<const std::type_info*,uinteger>>& input,
           const String&                                                 headline = EMPTY_STRING,
           const String&                                                 indent   = EMPTY_STRING );
 
    //==============================================================================================
    /// Helper for (bigger part of) #DumpFunctions.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_basecamp is included in the \alibdist.
    ///
    /// @param      input            A list of types and usage numbers.
    /// @param[out] output           A string to write to.
    /// @param      headline         The headline to write.
    /// @param      indent           Spaces to write before each entry.
    /// @param      tmpStrings       A buffer needed for internal use.
    //==============================================================================================
    ALIB_API static
    void            dumpFunctions (
                         const std::vector<std::pair<const std::type_info*,uinteger>>& input,
                         AString&                                                      output,
                         const String&                                                 headline,
                         const String&                                                 indent,
                         detail::DbgStringTable<uinteger>&                             tmpStrings );
 
 
    //==============================================================================================
    /// Lists all mapped types with either static or dynamic \e vtables.
    /// Along with each type, its default function implementations are given.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_basecamp is included in the \alibdist.
    ///
    /// @param staticVtables    If \c true, only types with static vtables are listed.
    ///                         Otherwise only those with dynamic vtables.
    /// @param includeFunctions If \c true for each type, the list of specialized functions are
    ///                         listed.
    /// @return A string containing the dump.
    //==============================================================================================
    ALIB_API static
    AString         DumpVTables( bool staticVtables,
                                 bool includeFunctions= false  );
 
    //==============================================================================================
    /// Internally used by methods #DumpVTables and #DumpAll.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_basecamp is included in the \alibdist.
    ///
    /// @param[out] target           The target string to write to.
    /// @param[out] vtableNames      Output parameter that receives the strings.
    /// @param      staticVtables    If \c true, only types with static vtables are listed.
    ///                              Otherwise only those with dynamic vtables.
    /// @param      includeFunctions If \c true, For each \e vtable the list of specialized
    ///                              function is written.
    //==============================================================================================
    ALIB_API static
    void            dumpVTables( AString&                                         target,
                                 detail::DbgStringTable<const detail::VTable*>&   vtableNames,
                                 bool                                             staticVtables,
                                 bool                                             includeFunctions );
 
#if ALIB_DEBUG_CONTAINERS
    //==============================================================================================
    /// Invokes \alib{containers;DbgDumpDistribution} on the internal hash table used to register
    /// and fetch implementations of custom box-functions.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_basecamp is included in the \alibdist
    ///   and compiler symbol \ref ALIB_DEBUG_CONTAINERS is given.
    ///
    /// @param[out] target              The target string to write to.
    /// @param      detailedBucketList  If \c true is given, for each bucket a line with its size
    ///                                 value and a "size bar" is written.
    //==============================================================================================
    ALIB_API static
    void            DumpCustomFunctionHashMapMetrics( AString& target, bool detailedBucketList );
#endif
 
    //==============================================================================================
    /// First, lists all mapped types with static, then those with dynamic \e vtables.
    /// Along with each type, its default function implementations are given.
    ///
    /// \par Availability
    ///   This method is included only if module \alib_basecamp is included in the \alibdist.
    ///
    /// @return A string containing the dump.
    //==============================================================================================
    ALIB_API static
    AString         DumpAll   ();
 
#include "alib/lang/callerinfo_methods.hpp"
#endif // ALIB_CAMP
 
    // #############################################################################################
    // Tools
    // #############################################################################################
#if ALIB_STRINGS
    //==============================================================================================
    /// Removes namespaces in the given \p{string}. The function is used with all methods that
    /// create string values containing type names.
    /// Note that custom namespaces might be added to static field #RemovableNamespaces
    /// before invoking any method.
    ///
    /// @param string      The string to remove the namespace from.
    /// @param startIndex  The index within the string to start searching for removable namespaces.
    /// @return A string containing the requested information.
    //==============================================================================================
    ALIB_API static
    AString&        removeNamespaces( AString& string, integer startIndex  );
 
    /// See method #removeNamespaces. Pre-initialized with <b>"alib::"</b>.
    ALIB_API static
    std::vector<String>   RemovableNamespaces;
 
#endif // ALIB_STRINGS
 
}; // class DbgBoxingDump
 
 
} // namespace alib[::boxing]
 
/// Type alias in namespace \b alib.
using     DbgBoxing=  boxing::DbgBoxing;
 
} // namespace [alib]
 
#endif // ALIB_DEBUG_BOXING
#endif // HPP_ALIB_BOXING_DBGBOXING