Description:

This namespace provides low- and high-level debug function for ALib Boxing.

To shorten custom type names, custom namespaces might be added to vector debug::RemovableNamespaces before invoking a function.

Note: Some of the functions are named with a non-capital letter which in ALib-types usually Their use is recommended, when writing custom "composite" debug-functions, as the various output parameters might be reused with subsequent invocations.

Availability: This namespace is only available if the compiler-symbol ALIB_DEBUG_BOXING is set.

The following functions are available independent of the ALib Build.

GetKnownVTables
GetKnownFunctionTypes
GetSpecificFunctionTypes
getFunctionTypes

The following functions become available if module ALib Strings is included in the ALib Build:

TypeName
typeName
removeNamespaces

All other functions become available if the module ALib Format is included in the ALib Build. If in addition symbol ALIB_DEBUG_CONTAINERS is given, then a final function becomes available:

DumpCustomFunctionHashMapMetrics

See also: Chapter 12.7 Debug Helpers of the Programmer's Manual of module ALib Boxing.

Type Index:
struct	DbgStringTable

Function Index:
ALIB_DLL void	DbgCheckIsInitialized ()

ALIB_DLL void	DbgCheckRegistration (detail::VTable *vtable, bool increaseUsageCounter)

void	DbgRegisterVTable (detail::VTable *vtable, detail::VTable::DbgFactoryType productionType)

AString	DumpAll ()

void	DumpCustomFunctionHashMapMetrics (AString &target, bool detailedBucketList)

AString	DumpFunctions (const std::vector< std::pair< const std::type_info *, uinteger > > &input, const String &headline, const String &indent)

void	dumpFunctions (const std::vector< std::pair< const std::type_info *, uinteger > > &input, AString &output, const String &headline, const String &indent, DbgStringTable< uinteger > &tmpStrings)

AString	DumpVTables (bool staticVtables, bool includeFunctions)

void	dumpVTables (AString &result, DbgStringTable< const detail::VTable * > &vtableNames, bool staticVtables, bool includeFunctions)

ALIB_DLL void	getFunctionTypes (const detail::FunctionTable &input, std::vector< std::pair< const std::type_info *, uinteger > > &output)

ALIB_DLL std::vector< std::pair< const std::type_info *, uinteger > >	GetKnownFunctionTypes ()

ALIB_DLL std::vector< detail::VTable * >	GetKnownVTables ()

std::vector< std::pair< const std::type_info *, uinteger > >	GetSpecificFunctionTypes (const Box &box)

std::vector< std::pair< const std::type_info *, uinteger > >	GetSpecificFunctionTypes (const detail::VTable *vtable)

AString &	removeNamespaces (AString &string, integer startIndex)

template<typename TBoxable>
AString	TypeInfo (const Box &box, const String &headline=A_CHAR("Boxing Information For Boxable Type: "), const String &indent=A_CHAR(" "))

template<typename TBoxable>
AString	TypeInfo (const String &headline=A_CHAR("Boxing Information For Boxable Type: "), const String &indent=A_CHAR(" "))

void	typeInfo (AString &target, const detail::VTable *vtable, const String &indent, bool srcIsPointer, bool srcIsStringType, bool srcIsUnboxableStringType, bool isValueTypeCustomized, bool isPointerTypeCustomized, bool fitsToPlaceholder, bool copyConstructible, bool triviallyDestructible, bool isUnboxable)

AString	TypeName (const Box &box)

AString	TypeName (const detail::VTable *vtable)

void	typeName (const detail::VTable *vtable, AString &result)

Variable Index:
std::vector< alib::String >	RemovableNamespaces
	See function removeNamespaces. Pre-initialized with "alib::".

Function Details:

◆ DbgCheckIsInitialized()

void alib::boxing::debug::DbgCheckIsInitialized ( )

Checks if ALib Boxing was correctly initialized. This is done with the creation of dynamic vtables, to detect global or static box objects which are initialized with data that is mapped to a type that no static vtable is defined for.

Available and used only in debug-compilations.

See also: Manual chapter 12.4 Global And Static Box Instances And Their Initialization.

Definition at line 1058 of file boxstrap.cpp.

◆ DbgCheckRegistration()

void alib::boxing::debug::DbgCheckRegistration	(	detail::VTable *	vtable,
		bool	increaseUsageCounter )

Checks for doubly-defined vtables, as well as for unregistered static vtables.

Available and used only in debug-compilations.

Parameters

vtable	The vtable to check.
increaseUsageCounter	Denotes if this is a use of the vtable or just a check.

Definition at line 1067 of file boxstrap.cpp.

Here is the call graph for this function:

◆ DbgRegisterVTable()

ALIB_DLL void alib::boxing::debug::DbgRegisterVTable	(	detail::VTable *	vtable,
		detail::VTable::DbgFactoryType	productionType )

Registers a virtual table for debug purposes. This function is invoked internally, when a dynamic vtable is created and when a static vtable is registered.

Statically created vtables have to be registered during bootstrap in debug-compilations. For this, macro ALIB_BOXING_BOOTSTRAP_VTABLE_DBG_REGISTER is available, which is empty in release compilations.

See also: Macros ALIB_BOXING_VTABLE_DECLARE and Programmer's Manual chapter 12.2 Optimizations With Static VTables.

Parameters

vtable	The vtable to register.
productionType	Denotes whether the vtable is a static constexpr object or dynamically created from template type VTableUnoptimized.

Definition at line 43 of file boxing_debug.cpp.

Here is the call graph for this function:

◆ DumpAll()

ALIB_DLL AString alib::boxing::debug::DumpAll ( )

First, lists all mapped types with static, then those with dynamic vtables. Along with each type, its default function implementations are given.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Returns: A string containing the dump.

Definition at line 322 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ DumpCustomFunctionHashMapMetrics()

ALIB_DLL void alib::boxing::debug::DumpCustomFunctionHashMapMetrics	(	AString &	target,
		bool	detailedBucketList )

Invokes DbgDumpDistribution on the internal hash table used to register and fetch implementations of custom box-functions.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbols ALIB_DEBUG_BOXING and ALIB_DEBUG_CONTAINERS are set.

Parameters

[out]	target	The target string to write to.
	detailedBucketList	If `true` is given, for each bucket a line with its size value and a "size bar" is written.

Definition at line 359 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ DumpFunctions()

ALIB_DLL alib::AString alib::boxing::debug::DumpFunctions	(	const std::vector< std::pair< const std::type_info *, uinteger > > &	input,
		const String &	headline = EMPTY_STRING,
		const String &	indent = EMPTY_STRING )

Takes a vector of pairs of std::type_info pointers and a usage counter and returns an AString with a sorted list of type names, including their counter information.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Parameters

input	A list of types.
headline	The headline to write.
indent	Spaces to write before each entry.

Returns: A list of demangled type names.

Definition at line 180 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ dumpFunctions()

ALIB_DLL void alib::boxing::debug::dumpFunctions	(	const std::vector< std::pair< const std::type_info *, uinteger > > &	input,
		AString &	output,
		const String &	headline,
		const String &	indent,
		DbgStringTable< uinteger > &	tmpStrings )

Helper for (bigger part of) DumpFunctions.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Parameters

	input	A list of types and usage numbers.
[out]	output	A string to write to.
	headline	The headline to write.
	indent	Spaces to write before each entry.
	tmpStrings	A buffer needed for internal use.

Definition at line 201 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ DumpVTables()

ALIB_DLL AString alib::boxing::debug::DumpVTables	(	bool	staticVtables,
		bool	includeFunctions = false )

Lists all mapped types with either static or dynamic vtables. Along with each type, its default function implementations are given.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Parameters

staticVtables	If `true`, only types with static vtables are listed. Otherwise only those with dynamic vtables.
includeFunctions	If `true` for each type, the list of specialized functions are listed.

Returns: A string containing the dump.

Definition at line 237 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ dumpVTables()

ALIB_DLL void alib::boxing::debug::dumpVTables	(	AString &	target,
		DbgStringTable< const detail::VTable * > &	vtableNames,
		bool	staticVtables,
		bool	includeFunctions )

Internally used by functions DumpVTables and DumpAll.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Parameters

[out]	target	The target string to write to.
[out]	vtableNames	Output parameter that receives the strings.
	staticVtables	If `true`, only types with static vtables are listed. Otherwise only those with dynamic vtables.
	includeFunctions	If `true`, For each vtable the list of specialized function is written.

Definition at line 259 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ getFunctionTypes()

void alib::boxing::debug::getFunctionTypes	(	const detail::FunctionTable &	input,
		std::vector< std::pair< const std::type_info *, uinteger > > &	output )

Collects all function declarator types of the given box-function table.

See also: The result can be conveniently passed to DumpFunctions.

Parameters

input	The function table to use.
output	The result vector to fill.

Definition at line 219 of file vtable.cpp.

◆ GetKnownFunctionTypes()

std::vector< std::pair< const std::type_info *, uinteger > > alib::boxing::debug::GetKnownFunctionTypes ( )

Returns a vector of std::type_info objects, representing all function types that either a default or a type specific implementation has been registered for.
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 std::numeric_limits<uinteger>::max().

The list includes the built-in function types.

See also: The result can be conveniently passed to DumpFunctions.

Returns: A vector of pairs of type information structs and usage numbers.

Definition at line 185 of file vtable.cpp.

◆ GetKnownVTables()

std::vector< detail::VTable * > alib::boxing::debug::GetKnownVTables ( )

Returns all vtable singletons that have been created during program execution so far. One vtable is created for each mapped type used.

See also: The result can be conveniently passed to DumpVTables.

Returns: A vector of pointers to objects of type detail::VTable.

Definition at line 159 of file vtable.cpp.

◆ GetSpecificFunctionTypes() [1/2]

std::vector< std::pair< const std::type_info *, uinteger > > alib::boxing::debug::GetSpecificFunctionTypes ( const Box & box )

inline

Convenience function: invokes GetSpecificFunctionTypes(const detail::VTable*) with the vtable of the box created or passed with the invocation.

See also: The result can be conveniently passed to DumpFunctions.

Parameters

box	A box that the vtable is used of.

Returns: A vector of type information structs.

Definition at line 132 of file boxing_debug.inl.

Here is the call graph for this function:

◆ GetSpecificFunctionTypes() [2/2]

std::vector< std::pair< const std::type_info *, uinteger > > alib::boxing::debug::GetSpecificFunctionTypes ( const detail::VTable * vtable )

inline

Collects all function declarator types, with type-specific implementations. Parameter vtable might for example be retrieved from a box instance with Box::DbgGetVTable.

See also: The result can be conveniently passed to DumpFunctions.

Parameters

vtable The vtable to get all function implementations for.

Returns: A vector of type information structs.

Definition at line 115 of file boxing_debug.inl.

Here is the call graph for this function:

◆ removeNamespaces()

ALIB_DLL AString & alib::boxing::debug::removeNamespaces	(	AString &	string,
		integer	startIndex )

Removes namespaces in the given string. The function is used with all debug-functions that create string values containing type names. Note that custom namespaces might be added to namespace variable debug::RemovableNamespaces before invoking any function.

Parameters

string	The string to remove the namespace from.
startIndex	The index within the string to start searching for removable namespaces.

Returns: A string containing the requested information.

Definition at line 86 of file boxing_debug.cpp.

◆ TypeInfo() [1/2]

template<typename TBoxable>

AString alib::boxing::debug::TypeInfo	(	const Box &	box,
		const String &	headline = A_CHAR("Boxing Information For Boxable Type: "),
		const String &	indent = A_CHAR(" " ) )

Collects necessary information from template type TBoxable and invokes typeInfo.
See function TypeInfo.

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Template Parameters

TBoxable The boxable type to investigate in.

Parameters

box	A box containing a "sample" of TBoxable.. If this box contains a different type than TBoxable, this function has undefined behavior.
headline	The headline to write.
indent	Spaces to write before each entry.

Returns: A string containing the requested information.

Definition at line 130 of file boxing_format_debug.inl.

Here is the call graph for this function:

◆ TypeInfo() [2/2]

template<typename TBoxable>

AString alib::boxing::debug::TypeInfo	(	const String &	headline = A_CHAR( "Boxing Information For Boxable Type: "),
		const String &	indent = A_CHAR( " " ) )

Returns human-readable information about the type TBoxable in respect to how boxing objects of this type is performed.

The implementation of this function creates a default value of 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 TypeInfo has to be used with an accordingly boxed "sample" of type TBoxable

Note: Does not work for type void*, which is not customizable anyhow (always boxed as void*).

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Template Parameters

TBoxable The boxable type to investigate in.

Parameters

headline	The headline to write.
indent	Spaces to write before each entry.

Returns: A string containing the requested information.

Definition at line 194 of file boxing_format_debug.inl.

Here is the call graph for this function:

◆ typeInfo()

ALIB_DLL void alib::boxing::debug::typeInfo	(	AString &	target,
		const detail::VTable *	vtable,
		const String &	indent,
		bool	srcIsPointer,
		bool	srcIsStringType,
		bool	srcIsUnboxableStringType,
		bool	isValueTypeCustomized,
		bool	isPointerTypeCustomized,
		bool	fitsToPlaceholder,
		bool	copyConstructible,
		bool	triviallyDestructible,
		bool	isUnboxable )

See function TypeInfo, which invokes this function using template parameter TBoxable

Availability: This function is an extension, which is injected by the higher-level module ALib Format and is accessed through the header file ALib.Format.H. Furthermore, the compiler-symbol ALIB_DEBUG_BOXING has to be set.

Parameters

[out]	target	The target string.
	vtable	The vtable of the mapped type.
	indent	Empty or a string of spaces that are alwys preprended before each entry.
	srcIsPointer	Denotes if TBoxable is a pointer type.
	srcIsStringType	Denotes if TBoxable is a string-type in the sense that a specialization of the struct ArrayTraits allows implicit access to character array data.
	srcIsUnboxableStringType	Denotes if TBoxable is a string-type that can, due to a specialization of the struct ArrayTraits be implicitly constructed from character array types.
	isValueTypeCustomized	Denotes if the value type of TBoxable is customized.
	isPointerTypeCustomized	Denotes if the pointer type of TBoxable is customized.
	fitsToPlaceholder	Denotes if the value type of TBoxable would fit to placeholder.
	copyConstructible	Denotes if the value type of TBoxable is copy constructible.
	triviallyDestructible	Denotes if the value type of TBoxable is trivially destructible.
	isUnboxable	Denotes if TBoxable is unboxable.

Definition at line 47 of file boxing_format_debug.cpp.

Here is the call graph for this function:

◆ TypeName() [1/2]

AString alib::boxing::debug::TypeName ( const Box & box )

inline

Convenience function: invokes TypeName(const detail::VTable*) with the vtable of the box created or passed with the invocation.

Availability: This function is included only if module ALib Strings is included in the ALib Build.

Parameters

box	The box to get the mapped type name for.

Returns: A string containing the requested information.

Definition at line 167 of file boxing_debug.inl.

Here is the call graph for this function:

◆ TypeName() [2/2]

AString alib::boxing::debug::TypeName ( const detail::VTable * vtable )

inline

Writes the (demangled) mapped type that the given vtable represents.

Availability: This function is included only if module ALib Strings is included in the ALib Build.

Parameters

vtable The vtable to get the mapped type name for.

Returns: A string containing the requested information.

Definition at line 152 of file boxing_debug.inl.

Here is the call graph for this function:

◆ typeName()

ALIB_DLL void alib::boxing::debug::typeName	(	const detail::VTable *	vtable,
		AString &	result )

Implementation of TypeName.

Availability: This function is included only if module ALib Strings is included in the ALib Build.

Parameters

	vtable	The vtable.
[out]	result	The target string to write the type information to.

Definition at line 103 of file boxing_debug.cpp.

Here is the call graph for this function:

Variable Details:

◆ RemovableNamespaces

ALIB_DLL std::vector< String > alib::boxing::debug::RemovableNamespaces

Initial value:

{
    A_CHAR( "alib::boxing::" ),
    A_CHAR( "alib::"         ),
}

See function removeNamespaces. Pre-initialized with "alib::".

Definition at line 97 of file boxing_debug.cpp.

Description:

Type Index:

Function Index:

Variable Index:

Function Details:

◆ DbgCheckIsInitialized()

◆ DbgCheckRegistration()

◆ DbgRegisterVTable()

◆ DumpAll()

◆ DumpCustomFunctionHashMapMetrics()

◆ DumpFunctions()

◆ dumpFunctions()

◆ DumpVTables()

◆ dumpVTables()

◆ getFunctionTypes()

◆ GetKnownFunctionTypes()

◆ GetKnownVTables()

◆ GetSpecificFunctionTypes() [1/2]

◆ GetSpecificFunctionTypes() [2/2]

◆ removeNamespaces()

◆ TypeInfo() [1/2]

◆ TypeInfo() [2/2]

◆ typeInfo()

◆ TypeName() [1/2]

◆ TypeName() [2/2]

◆ typeName()

Variable Details:

◆ RemovableNamespaces