vtable.inl

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_DETAIL_VTABLE
#define HPP_ALIB_BOXING_DETAIL_VTABLE 1
#pragma once
#if !defined(HPP_ALIB_BOXING_BOXING)
#   error "ALib sources with ending '.inl' must not be included from outside."
#endif
 
namespace alib {  namespace boxing {
 
/// This namespace implements internals of namespace #alib::boxing.
namespace detail {
 
//==================================================================================================
/// This struct is used internally with \alib_boxing_nl  to provide run-time type information
/// and virtual method invocations to boxed values.
/// A singleton instance of a derived type of this class is attached to each \alib{boxing;Box}.
/// Such derived type is generated using templated derived struct \alib{boxing::detail;VTable}.
//==================================================================================================
struct FunctionTable
{
    // #############################################################################################
    // Fields
    // #############################################################################################
    FHashcode         ::Signature    fHashcode = nullptr;  ///< Entry for built-in function \alib{boxing;FHashcode}.
    FIsNotNull        ::Signature    fIsNotNull= nullptr;  ///< Entry for built-in function \alib{boxing;FIsNotNull}.
    FEquals           ::Signature    fEquals   = nullptr;  ///< Entry for built-in function \alib{boxing;FEquals}.
    FIsLess           ::Signature    fIsLess   = nullptr;  ///< Entry for built-in function \alib{boxing;FIsLess}.
    FIsTrue           ::Signature    fIsTrue   = nullptr;  ///< Entry for built-in function \alib{boxing;FIsTrue}.
#if ALIB_MONOMEM
    FClone            ::Signature    fClone    = nullptr;  ///< Entry for built-in function \alib{boxing;FClone}.
#endif
#if ALIB_STRINGS
    FAppend<character,lang::HeapAllocator>::Signature    fAppend   = nullptr;  ///< Entry for built-in function \alib{boxing;FAppend;FAppend<character>}.
#endif
#if ALIB_DEBUG
    mutable uinteger DbgCntInvocationsFHashcode =0;   ///< Debug-compilation counter for the number of invocations.
    mutable uinteger DbgCntInvocationsFIsNotNull=0;   ///< Debug-compilation counter for the number of invocations.
    mutable uinteger DbgCntInvocationsFEquals   =0;   ///< Debug-compilation counter for the number of invocations.
    mutable uinteger DbgCntInvocationsFIsLess   =0;   ///< Debug-compilation counter for the number of invocations.
    mutable uinteger DbgCntInvocationsFIsTrue   =0;   ///< Debug-compilation counter for the number of invocations.
 #if ALIB_MONOMEM
    mutable uinteger DbgCntInvocationsFClone    =0;   ///< Debug-compilation counter for the number of invocations.
  #endif
  #if ALIB_STRINGS
    mutable uinteger DbgCntInvocationsFAppend   =0;   ///< Debug-compilation counter for the number of invocations.
  #endif
#endif
 
    // #############################################################################################
    // Get
    // #############################################################################################
#if DOXYGEN
   /// Receives the function of type \p{TFDecl}.
   ///
   /// @tparam TFDecl       The function type to get.
   /// @param  isInvocation If \c true, the invocation counter is increased.
   ///                      This parameter is defined only in debug-compilations.
   /// @return The function found, or \c nullptr in case it was not defined.
    template<typename TFDecl>
    typename TFDecl::Signature
    Get( bool isInvocation ) const;
#else
    template<typename TFDecl>  ATMP_T_IF(FHashcode         ::Signature, ATMP_EQ(TFDecl, FHashcode         ))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFHashcode ; ) return fHashcode ; }
    template<typename TFDecl>  ATMP_T_IF(FIsNotNull        ::Signature, ATMP_EQ(TFDecl, FIsNotNull        ))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFIsNotNull; ) return fIsNotNull; }
    template<typename TFDecl>  ATMP_T_IF(FEquals           ::Signature, ATMP_EQ(TFDecl, FEquals           ))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFEquals   ; ) return fEquals   ; }
    template<typename TFDecl>  ATMP_T_IF(FIsLess           ::Signature, ATMP_EQ(TFDecl, FIsLess           ))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFIsLess   ; ) return fIsLess   ; }
    template<typename TFDecl>  ATMP_T_IF(FIsTrue           ::Signature, ATMP_EQ(TFDecl, FIsTrue           ))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFIsTrue   ; ) return fIsTrue   ; }
  IF_ALIB_MONOMEM(
    template<typename TFDecl>  ATMP_T_IF(FClone            ::Signature, ATMP_EQ(TFDecl, FClone            ))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFClone    ; ) return fClone    ; } )
  IF_ALIB_STRINGS(
    template<typename TFDecl>  ATMP_T_IF(FAppend<character ALIB_COMMA lang::HeapAllocator>::Signature, ATMP_EQ(TFDecl, FAppend<character ALIB_COMMA lang::HeapAllocator>))  Get(ALIB_DBG( bool isInvocation )) const { ALIB_DBG( if(isInvocation) ++DbgCntInvocationsFAppend   ; ) return fAppend   ; } )
 
    template<typename TFDecl>  ATMP_T_IF(typename TFDecl::Signature,    !ATMP_EQ(TFDecl, FHashcode )
                                                                     && !ATMP_EQ(TFDecl, FIsNotNull)
                                                                     && !ATMP_EQ(TFDecl, FEquals   )
                                                                     && !ATMP_EQ(TFDecl, FIsLess   )
                                                                     && !ATMP_EQ(TFDecl, FIsTrue   )
                                             IF_ALIB_MONOMEM(  && !ATMP_EQ(TFDecl, FClone    )          )
                                             IF_ALIB_STRINGS( && !ATMP_EQ(TFDecl, FAppend<character ALIB_COMMA lang::HeapAllocator>)  )
                                        )
    Get(ALIB_DBG( bool isInvocation )) const
    {
        return reinterpret_cast<typename TFDecl::Signature>( getCustom( typeid(TFDecl) ALIB_DBG(, isInvocation ) ) );
    }
#endif
 
 
 
    // #############################################################################################
    // Set
    // #############################################################################################
#if DOXYGEN
   /// Registers an implementation of the function of type \p{TFDecl}.
   ///
   /// @tparam TFDecl         The function type to register.
   /// @param  implementation The implementation of the function.
    template<typename TFDecl>
    void  Set( typename TFDecl::Signature implementation );
#else
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FHashcode         ))  Set( FHashcode         ::Signature impl) { fHashcode = impl; }
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FIsNotNull        ))  Set( FIsNotNull        ::Signature impl) { fIsNotNull= impl; }
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FEquals           ))  Set( FEquals           ::Signature impl) { fEquals   = impl; }
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FIsLess           ))  Set( FIsLess           ::Signature impl) { fIsLess   = impl; }
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FIsTrue           ))  Set( FIsTrue           ::Signature impl) { fIsTrue   = impl; }
  IF_ALIB_MONOMEM(
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FClone            ))  Set( FClone            ::Signature impl) { fClone    = impl; } )
  IF_ALIB_STRINGS(
    template<typename TFDecl>  ATMP_VOID_IF(ATMP_EQ(TFDecl, FAppend<character ALIB_COMMA lang::HeapAllocator>))  Set( FAppend<character ALIB_COMMA lang::HeapAllocator>::Signature impl) { fAppend   = impl; } )
 
 
    template<typename TFDecl>  ATMP_VOID_IF(   !ATMP_EQ(TFDecl, FHashcode )
                                            && !ATMP_EQ(TFDecl, FIsNotNull)
                                            && !ATMP_EQ(TFDecl, FEquals   )
                                            && !ATMP_EQ(TFDecl, FIsLess   )
                                            && !ATMP_EQ(TFDecl, FIsTrue   )
                          IF_ALIB_MONOMEM(  && !ATMP_EQ(TFDecl, FClone    )          )
                          IF_ALIB_STRINGS(  && !ATMP_EQ(TFDecl, FAppend<character ALIB_COMMA lang::HeapAllocator>)  )
                                           )
    Set( typename TFDecl::Signature impl )
    {
        return setCustom( typeid(TFDecl), reinterpret_cast<void*>( impl ) );
    }
#endif
 
    // #############################################################################################
    // Cleanup (needed for debug-builds in shutdown)
    // #############################################################################################
#if (ALIB_MONOMEM && ALIB_DEBUG)  || DOXYGEN
    /// Needs to be called only in debug versions to shut down internal hashtables cleanly.
    ALIB_API static void Shutdown();
#else
    inline   static void Shutdown() {}
#endif
 
 
    // #############################################################################################
    // internals
    // #############################################################################################
    protected:
       #if DOXYGEN
       /// Non-inline implementation of #Get used in the case of non-built-in functions.
       /// @param  rtti         The \c typeid of the function to get.
       /// @param  isInvocation If \c true, the invocation counter is increased.
       ///                      This parameter is defined only in debug-compilations.
       /// @return The pointer to the box-function.
       ALIB_API void*    getCustom( const std::type_info& rtti, bool isInvocation )  const;
       #else
 
       ALIB_API void*    getCustom( const std::type_info& rtti
                                             ALIB_DBG(        , bool isInvocation )) const;
       #endif
 
       /// Non-inline implementation of #Set #Get used in the case of non-built-in functions.
       /// @param  rtti           The \c typeid of the function to register.
       /// @param  implementation The implementation of the function.
       ALIB_API void     setCustom( const std::type_info& rtti, void* implementation );
 
}; // FunctionTable
 
//==================================================================================================
/// The default box-functions set.
//==================================================================================================
extern ALIB_API  FunctionTable DEFAULT_FUNCTIONS;
 
 
//==================================================================================================
/// This struct is used internally with \alib_boxing_nl  to provide run-time type information
/// and virtual method invocations to boxed values.
/// A singleton instance of this struct is attached to each \alib{boxing;Box}.
//==================================================================================================
struct VTable
{
    /// Denotes if the mapped type is value type, a pointer type, an enum or an array.
    /// The latter is not specified by an enum element, but rather is \c true for all enum
    /// elements that have a value greater than \c 0. The value in this case provides the size
    /// of the array's element type.
    enum MappingType :  integer
    {
        Value       =  0, ///< Value boxing.
        Pointer     = -1, ///< Pointer boxing.
        Enum        = -2, ///< Enum type boxing
    };
 
    /// Information about the encapsulated type. In case of arrays, this field is
    /// equal to \c typeid(void).
    const std::type_info&   Type;
 
    /// In case of array types, information about the element type. Otherwise this field is
    /// equal to \c typeid(void).
    const std::type_info&   ElementType;
 
    /// Denotes if the mapped type is a value type, a pointer type, an enum or an array.
    /// In the case of array types, the enum element value provides the size of the array's element
    /// type (a value greater than \c 0).
    const MappingType       Mapping;
 
    /// The number of relevant bytes used in the placeholder.
    ///
    /// \see
    ///   The documentation of TMP struct \alib{boxing;T_SizeInPlaceholder} provides details on
    ///   and rationals for the existence of this property.
    const unsigned int      PlaceholderUsage;
 
    /// Box-functions attached with \alib{boxing;BootstrapRegister}.
    FunctionTable           Functions;
 
    #if ALIB_DEBUG
        /// These flags are available in debug-compilations only. Denotes whether this vtable
        /// is statically or dynamically created. In case of \b Unregistered, a customized
        /// vtable was not properly registered on bootstrap.
        enum class DbgFactoryType
        {
            Unregistered, ///< Not registered, yet.
            Static      , ///< A static VTable is in place.
            Dynamic     , ///< The VTable is created dynamically from templated type \b VTableTT.
        };
 
        /// Debug information.
        DbgFactoryType DbgProduction = DbgFactoryType::Unregistered;
 
        ///  Counter for the number of unbox operations and function invocations made on boxes
        ///  that used this \e vtable. Precisely, the counter is increased with invocations
        ///  of
        ///  \alib{boxing;Box::Unbox},
        ///  \alib{boxing;Box::UnboxArray},
        ///  \alib{boxing;Box::UnboxElement},
        ///  \alib{boxing;Box::TypeID} and
        ///  \alib{boxing;Box::GetFunction}.
        ///
        ///  Available only with debug-builds.
        uinteger DbgCntUsage = 0;
    #endif
 
    //==============================================================================================
    /// Constructor.
    ///
    /// @param type             Type information of the derived \b VTable type.
    /// @param elementType      Type information of the elements of the boxed array.
    /// @param mapping          The type of boxing: value, pointer, enum or arrays.
    /// @param placeholderUsage The size of elements of the boxed array.
    //==============================================================================================
    VTable( const std::type_info&   type,
            const std::type_info&   elementType,
            MappingType             mapping,
            unsigned int            placeholderUsage )
     : Type            ( type             )
     , ElementType     ( elementType      )
     , Mapping         ( mapping          )
     , PlaceholderUsage( placeholderUsage )
     {}
 
 
    //==============================================================================================
    /// Virtual destructor.<br>
    /// Note: This is not really needed and empty.  Because derived class \b %VTable derives from
    /// virtual type \alib{singletons;Singleton}, having this destructor allows cleaning memory
    /// on termination "more precisely" and reduce warnings raised by analytics tools like
    /// \b valgrind.
    //==============================================================================================
    virtual ~VTable()
    {}
 
    //==============================================================================================
    /// Returns \c true if this vtable represents boxed array types. In this case, method
    /// \ref alib::boxing::Box::UnboxLength "Box::UnboxLength"
    /// will return the length of the array and
    /// \ref alib::boxing::Box::UnboxElement "Box::UnboxElement" may be used to
    /// access elements of the array.
    ///
    /// @return \c true if this vtable is representing an array type, \c false otherwise.
    //==============================================================================================
    bool        IsArray()                                                                  const
    {
        return Mapping > 0;
    }
 
    //==============================================================================================
    /// Returns \c true if this vtable represents mapped pointer type.
    ///
    /// @return \c true if this vtable is representing a pointer type, \c false otherwise.
    //==============================================================================================
    bool        IsPointer()                                                                const
    {
        return Mapping == MappingType::Pointer;
    }
 
    //==============================================================================================
    /// Returns \c true if this vtable represents a scoped or non-scoped enum type.
    ///
    /// @return \c true if this vtable is representing an enum type, \c false otherwise.
    //==============================================================================================
    bool        IsEnum()                                                                   const
    {
        return Mapping == MappingType::Enum;
    }
}; // struct VTable
 
 
// #################################################################################################
// VTable
// #################################################################################################
#if ALIB_DEBUG_BOXING
 
    //==============================================================================================
    /// Registers a virtual table for debug purposes.
    /// This function is invoked internally, when a dynamic \e vtable is created and
    /// when a static \e vtable is registered.
    ///
    /// Statically created \e vtables have to be registered during bootstrap in debug-compilations.
    /// For this, macro \ref ALIB_BOXING_BOOTSTRAP_VTABLE_DBG_REGISTER is available, which is empty
    /// in release compilations.
    ///
    /// \see
    ///   Macros ALIB_BOXING_VTABLE_DECLARE and \ref alib_mod_boxing "Programmer's Manual" chapter
    ///   \ref alib_boxing_more_opt_staticvt.
    ///
    /// @param vtable         The vtable to register.
    /// @param productionType Denotes whether the \p{vtable} is a static constexpr object or
    ///                       dynamically created from template type \b VTableTT.
    //==============================================================================================
    ALIB_API
    void DbgRegisterVTable( detail::VTable* vtable, detail::VTable::DbgFactoryType productionType );
 
#endif // ALIB_DEBUG_BOXING
 
//==================================================================================================
/// This is a templated derivate of class \b VTable. It is necessary to create singletons for
/// arbitrary mapped types.
///
/// \see
///   Chapter \ref alib_boxing_more_opt_staticvt_bg
///   of the \alib_boxing "Programmer's Manual" of module \alib_boxing_nl.
///
/// ## Friends ##
/// class \alib{singletons;Singleton;Singleton< VTableTT<TPlainOrArray; TMapped> >}
///
/// @tparam TPlainOrArray   Either type \alib{boxing;detail::TPlain} or \alib{boxing;detail::TArrayOf}.
/// @tparam TMapped         The mapped type.
//==================================================================================================
template<typename TPlainOrArray, typename TMapped>
class VTableTT  : public VTable
                , public Singleton< VTableTT<TPlainOrArray, TMapped> >
{
    #if !DOXYGEN
        friend singletons::Singleton< VTableTT<TPlainOrArray, TMapped> >;
    #endif
 
    private:
        /// Constructor. Passes parameters as expected by parent class \b VTable.
        ///
        /// This constructor is private, and class \b %Singleton is a friend, which makes each
        /// template instance of this class being a 'strict' singleton (only that singleton instance
        /// exists).
        constexpr VTableTT()
        : VTable( ATMP_EQ(TPlainOrArray, TPlain )  ? typeid(TMapped)
                                                   : typeid(TMapped[1]),
 
                  ATMP_EQ(TPlainOrArray, TPlain )  ? typeid(void)
                                                   : typeid(TMapped),
 
                  ATMP_EQ(TPlainOrArray, TArrayOf) ? VTable::MappingType(sizeof(TMapped))
                                                   : ATMP_IS_PTR(TMapped)
                                                   ? VTable::MappingType::Pointer
                                                   : ATMP_IS_ENUM(TMapped)
                                                   ? VTable::MappingType::Enum
                                                   : VTable::MappingType::Value    ,
 
 
                  ATMP_EQ(TPlainOrArray, TPlain )  ? T_SizeInPlaceholder<TMapped>::value
                                                   : sizeof(Placeholder)
                )
        {
            #if ALIB_DEBUG_BOXING
                DbgRegisterVTable( this, DbgFactoryType::Dynamic );
            #endif
        }
};
 
 
#if ALIB_DEBUG_BOXING || DOXYGEN
 
/// Checks if \alib_boxing_nl was correctly initialized.
/// This is done with the creation of \ref alib_boxing_more_opt_staticvt "dynamic vtables",
/// to detect global or static box objects which are initialized with data that is mapped to
/// a type that no static \e vtable is defined for.
///
/// Available and used only in debug-compilations.
///
/// \see
///   Manual chapter \ref alib_boxing_more_static_instances.
ALIB_API void DbgCheckIsInitialized();
 
/// Checks for doubly-defined \e vtables, as well as for unregistered
/// \ref alib_boxing_more_opt_staticvt "static vtables".
///
/// Available and used only in debug-compilations.
/// @param vtable                The \e vtable to check.
/// @param increaseUsageCounter  Denotes if this is a use of the vtable or just a check.
ALIB_API void DbgCheckRegistration( detail::VTable* vtable, bool increaseUsageCounter );
#else
inline void DbgCheckIsInitialized()                         {}
inline void DbgCheckRegistration (detail::VTable*, bool )   {}
#endif
 
 
 
 
//==================================================================================================
/// Method #Get of the default version of this struct creates a \alib{boxing::detail;VTable}
/// dynamically.
/// For this, a corresponding templated \alib{singletons;Singleton} type
/// \alib{boxing::detail;VTableTT}, according to given template parameter \p{TMapping} is returned.
///
/// For optimization purposes (code size as well as execution performance), this struct might
/// be specialized for selected a mapped types, to return static singleton object.
///
/// Specializations for all C++ fundamental types are given. Furthermore, various different
/// \alibmods provide such specializations for types they introduced and that are boxed.
///
/// \see
///   Chapter \ref alib_boxing_more_opt_staticvt_howto of the Programmer's Manual
///   of \alib_boxing_nl.
///
/// @tparam TMapping  The mapped type to receive a \e vtable for. Has to be of either type
///                   \alib{boxing;TMappedTo<T>} or \alib{boxing;TMappedToArrayOf<T>}.
//==================================================================================================
template<typename TMapping>
struct  T_VTableFactory
{
    /// Returns a strict singleton \e vtable responsible for boxing mapped type \p{TMapping}.
    /// @return The requested \e vtable singleton.
    static constexpr VTable* Get()
    {
        DbgCheckIsInitialized();
 
        VTable* result=  &VTableTT<typename TMapping::PlainOrArray, typename TMapping::Type>::GetSingleton();
 
        DbgCheckRegistration( result, false );
 
        return result;
    }
 
};
 
 
}}} // namespace [alib::boxing::detail]
 
 
//##################################################################################################
//#######################################     Macros     ###########################################
//##################################################################################################
 
#define ALIB_BOXING_VTABLE_DECLARE( TMapped, Identifier )                                          \
namespace alib::boxing::detail {                                                                   \
extern ALIB_API VTable SNGLTN_ ## Identifier;                                                      \
template<> struct  T_VTableFactory< TMappedTo<TMapped> >                                           \
{ static constexpr VTable* Get() { return  &SNGLTN_ ## Identifier; } };   }                        \
 
#define ALIB_BOXING_VTABLE_DECLARE_ARRAYTYPE( TMapped, Identifier )                                \
namespace alib::boxing::detail {                                                                   \
extern ALIB_API VTable SNGLTN_ ## Identifier;                                                      \
template<> struct  T_VTableFactory< TMappedToArrayOf<TMapped> >                                    \
{ static constexpr VTable* Get() { return  &SNGLTN_ ## Identifier; } };   }                        \
 
 
#define ALIB_BOXING_VTABLE_DEFINE( TMapped, Identifier )                                           \
alib::boxing::detail::VTable alib::boxing::detail::SNGLTN_ ## Identifier                           \
( typeid(TMapped), typeid(void)  ,                                                                 \
   std::is_pointer<TMapped>::value                                                                 \
 ? VTable::MappingType::Pointer                                                                    \
 : std::is_enum<TMapped>::value                                                                    \
 ? VTable::MappingType::Enum                                                                       \
 : VTable::MappingType::Value   ,                                                                  \
 alib::boxing::T_SizeInPlaceholder<TMapped>::value);                                               \
 
#define ALIB_BOXING_VTABLE_DEFINE_ARRAYTYPE( TMapped, Identifier )                                 \
alib::boxing::detail::VTable alib::boxing::detail::SNGLTN_ ## Identifier                           \
(typeid(TMapped[1]) , typeid(TMapped), VTable::MappingType(sizeof(TMapped)), sizeof(Placeholder)); \
 
 
#if ALIB_DEBUG_BOXING
#   define ALIB_BOXING_BOOTSTRAP_VTABLE_DBG_REGISTER( Identifier )                                 \
DbgRegisterVTable( &alib::boxing::detail::SNGLTN_ ## Identifier,                                   \
                   alib::boxing::detail::VTable::DbgFactoryType::Static );
#else
#   define ALIB_BOXING_BOOTSTRAP_VTABLE_DBG_REGISTER( Identifier )
#endif
 
#endif // HPP_ALIB_BOXING_DETAIL_VTABLE