ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
boxing_format_debug.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_boxing of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8#if ALIB_DEBUG_BOXING
11
12//==================================================================================================
13/// Template class implementing a monotonically allocated vector of variadic tuples whose first
14/// element is of type \alib{strings;TString<TChar>;String}.
15///
16/// When new tuples are added with the method #Add, then memory for copying the provided string is
17/// allocated using an internal field of type \alib{MonoAllocator}.
18/// This allows adding single strings, which are allocated in bigger memory buffers.
19///
20/// Standard vector operations, including insertions and deletions are still allowed.
21/// In other words, it is allowed to store string objects which are pointing to string data that
22/// is \b not allocated in the internal buffers.
23///
24/// The associated values are especially useful when the vector is sorted (e.g., using
25/// \c std::sort), because such associations will be kept intact and allow referencing back
26/// to whatever the strings represents.
27///
28/// \par Availability
29/// This function is an extension, which is injected by the higher-level module \alib_format and
30/// is accessed through the header file \implude{Format}.
31/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
32//==================================================================================================
33template< typename... TAssociatedTypes >
34struct DbgStringTable : public std::vector<std::tuple<String, TAssociatedTypes...>>
35{
36 /// Shortcut to the <c>std::tuple</c>-type that instantiations of this template class store.
37 using ElementType= std::tuple<String, TAssociatedTypes...>;
38
39 /// Shortcut to the base type of this type.
40 using Base = std::vector<ElementType>;
41
42 /// Allocator for making copies of inserted strings
44
45 /// Constructor.
46 /// @param monoAllocator A mono allocator used to create copies of the inserted strings
47 DbgStringTable( MonoAllocator& monoAllocator )
48 : allocator(monoAllocator)
49 {}
50
51 /// Adds a tuple. The contents of the string of the tuple (its first element) is copied
52 /// from the given string \p{src}. The memory for this string is allocated using
53 /// the allocator provided in the constructor.<br>
54 /// The other members of the tuple added are forwarded from variadic parameter block \p{args}.
55 ///
56 /// @param src The string to copy into the first member of the tuple.
57 /// @param args Variadic arguments to fill the rest of the inserted tuple.
58 ///
59 /// @return A reference to the string that was added.
60 template <typename... TArgs>
61 String& Add( const String& src, TArgs&&... args )
62 {
63 // on errors, see note above!
64 Base::emplace_back( String(allocator, src), std::forward<TArgs>(args)... );
65 return std::get<0>( std::vector<std::tuple<String, TAssociatedTypes...>>::back() );
66 }
67};
68
69/// See function #TypeInfo, which invokes this function using template parameter \p{TBoxable}
70///
71/// \par Availability
72/// This function is an extension, which is injected by the higher-level module \alib_format and
73/// is accessed through the header file \implude{Format}.
74/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
75///
76/// @param[out] target The target string.
77/// @param vtable The vtable of the mapped type.
78/// @param indent Empty or a string of spaces that are alwys preprended
79/// before each entry.
80/// @param srcIsPointer Denotes if \p{TBoxable} is a pointer type.
81/// @param srcIsStringType Denotes if \p{TBoxable} is a string-type in the sense
82/// that a specialization of the
83/// struct \alib{characters;ArrayTraits} allows implicit access
84/// to character array data.
85/// @param srcIsUnboxableStringType Denotes if \p{TBoxable} is a string-type that can,
86/// due to a specialization of the
87/// struct \alib{characters;ArrayTraits} be implicitly
88/// constructed from character array types.
89/// @param isValueTypeCustomized Denotes if the value type of \p{TBoxable} is customized.
90/// @param isPointerTypeCustomized Denotes if the pointer type of \p{TBoxable} is
91/// customized.
92/// @param fitsToPlaceholder Denotes if the value type of \p{TBoxable} would fit to
93/// placeholder.
94/// @param copyConstructible Denotes if the value type of \p{TBoxable} is
95/// copy constructible.
96/// @param triviallyDestructible Denotes if the value type of \p{TBoxable} is
97/// trivially destructible.
98/// @param isUnboxable Denotes if \p{TBoxable} is unboxable.
100void typeInfo( AString& target,
101 const detail::VTable* vtable,
102 const String& indent,
103 bool srcIsPointer,
104 bool srcIsStringType,
105 bool srcIsUnboxableStringType,
106 bool isValueTypeCustomized,
107 bool isPointerTypeCustomized,
108 bool fitsToPlaceholder,
109 bool copyConstructible,
110 bool triviallyDestructible,
111 bool isUnboxable );
112
113
114/// Collects necessary information from template type \p{TBoxable} and invokes
115/// #typeInfo.<br>
116/// See function #TypeInfo.
117///
118/// \par Availability
119/// This function is an extension, which is injected by the higher-level module \alib_format and
120/// is accessed through the header file \implude{Format}.
121/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
122///
123/// @tparam TBoxable The boxable type to investigate in.
124/// @param box A box containing a "sample" of \p{TBoxable.}. If this box contains a different
125/// type than \p{TBoxable}, this function has undefined behavior.
126/// @param headline The headline to write.
127/// @param indent Spaces to write before each entry.
128/// @return A string containing the requested information.
129template<typename TBoxable>
130AString TypeInfo( const Box& box,
131 const String& headline= A_CHAR("Boxing Information For Boxable Type: "),
132 const String& indent = A_CHAR(" " ) )
133{
134 AString target;
135 using TSrc= std::remove_cv_t<TBoxable>;
136 using TVal= ALIB_TVALUE(TBoxable);
137
138 // repeat twice to get auto-tabs adjusted
140 Formatter& formatter= *Formatter::Default;
141 formatter.Reset();
142 for( int theSakeOfAutoTabs= 0 ; theSakeOfAutoTabs < 2 ; ++theSakeOfAutoTabs )
143 {
144 NString512 demangled(typeid(TSrc) );
145 target.Reset() << headline << demangled << NEW_LINE;
146 removeNamespaces( target, headline.Length() );
147
148 if( std::same_as<TSrc, std::nullptr_t> )
149 {
150 target << indent << "'std::nullptr_t' sets a box to void state" << NEW_LINE;
151 return target;
152 }
153
154 typeInfo( target,
155 box.DbgGetVTable(),
156 indent,
157 std::is_pointer_v<TSrc>,
162 sizeof(boxing::Placeholder) <= sizeof(TVal),
163 std::is_copy_constructible <TVal>::value,
164 std::is_trivially_destructible<TVal>::value,
165 boxing::IsUnboxable <TSrc > );
166
167 }
168 return target;
169}
170
171/// Returns human-readable information about the type \p{TBoxable} in respect to how boxing
172/// objects of this type is performed.
173///
174/// The implementation of this function creates a default value of \p{TBoxable}, boxes this
175/// and returns the result of #TypeInfo(const Box&,const String&,const String&).
176/// Hence, for types that are not default constructible, inner function \b %TypeInfo
177/// has to be used with an accordingly boxed "sample" of type \p{TBoxable}
178///
179/// \note
180/// Does not work for type \c void*, which is not customizable anyhow
181/// (always boxed as \c void*).
182///
183///
184/// \par Availability
185/// This function is an extension, which is injected by the higher-level module \alib_format and
186/// is accessed through the header file \implude{Format}.
187/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
188///
189/// @tparam TBoxable The boxable type to investigate in.
190/// @param headline The headline to write.
191/// @param indent Spaces to write before each entry.
192/// @return A string containing the requested information.
193template<typename TBoxable>
194AString TypeInfo( const String& headline = A_CHAR( "Boxing Information For Boxable Type: ") ,
195 const String& indent = A_CHAR( " " ) )
196
197{ return TypeInfo<TBoxable>( TBoxable(), headline, indent ); }
198
199
200// #############################################################################################
201// Dump
202// #############################################################################################
203/// Takes a vector of pairs of \c std::type_info pointers and a usage counter and returns an
204/// \b AString with a sorted list of type names, including their counter information.
205///
206/// \par Availability
207/// This function is an extension, which is injected by the higher-level module \alib_format and
208/// is accessed through the header file \implude{Format}.
209/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
210///
211/// @param input A list of types.
212/// @param headline The headline to write.
213/// @param indent Spaces to write before each entry.
214/// @return A list of demangled type names.
217 const std::vector<std::pair<const std::type_info*,uinteger>>& input,
218 const String& headline = EMPTY_STRING,
219 const String& indent = EMPTY_STRING );
220
221/// Helper for (bigger part of) #DumpFunctions.
222///
223/// \par Availability
224/// This function is an extension, which is injected by the higher-level module \alib_format and
225/// is accessed through the header file \implude{Format}.
226/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
227/// @param input A list of types and usage numbers.
228/// @param[out] output A string to write to.
229/// @param headline The headline to write.
230/// @param indent Spaces to write before each entry.
231/// @param tmpStrings A buffer needed for internal use.
233void dumpFunctions ( const std::vector<std::pair<const std::type_info*,uinteger>>& input,
234 AString& output,
235 const String& headline,
236 const String& indent,
237 DbgStringTable<uinteger>& tmpStrings );
238
239
240/// Lists all mapped types with either static or dynamic \e vtables.
241/// Along with each type, its default function implementations are given.
242///
243/// \par Availability
244/// This function is an extension, which is injected by the higher-level module \alib_format and
245/// is accessed through the header file \implude{Format}.
246/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
247/// @param staticVtables If \c true, only types with static vtables are listed.
248/// Otherwise only those with dynamic vtables.
249/// @param includeFunctions If \c true for each type, the list of specialized functions are
250/// listed.
251/// @return A string containing the dump.
253AString DumpVTables( bool staticVtables,
254 bool includeFunctions= false );
255
256/// Internally used by functions #DumpVTables and #DumpAll.
257///
258/// \par Availability
259/// This function is an extension, which is injected by the higher-level module \alib_format and
260/// is accessed through the header file \implude{Format}.
261/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
262/// @param[out] target The target string to write to.
263/// @param[out] vtableNames Output parameter that receives the strings.
264/// @param staticVtables If \c true, only types with static vtables are listed.
265/// Otherwise only those with dynamic vtables.
266/// @param includeFunctions If \c true, For each \e vtable the list of specialized
267/// function is written.
269void dumpVTables( AString& target,
270 DbgStringTable<const detail::VTable*>& vtableNames,
271 bool staticVtables,
272 bool includeFunctions );
273
274#if ALIB_DEBUG_CONTAINERS
275 /// Invokes \alib{containers;DbgDumpDistribution} on the internal hash table used to register
276 /// and fetch implementations of custom box-functions.
277 ///
278 /// \par Availability
279 /// This function is an extension, which is injected by the higher-level module \alib_format
280 /// and is accessed through the header file \implude{Format}.
281 /// Furthermore, the compiler-symbols \ref ALIB_DEBUG_BOXING and \ref ALIB_DEBUG_CONTAINERS
282 /// are set.
283 /// @param[out] target The target string to write to.
284 /// @param detailedBucketList If \c true is given, for each bucket a line with its size
285 /// value and a "size bar" is written.
287 void DumpCustomFunctionHashMapMetrics( AString& target, bool detailedBucketList );
288
289#endif
290
291/// First, lists all mapped types with static, then those with dynamic \e vtables.
292/// Along with each type, its default function implementations are given.
293///
294/// \par Availability
295/// This function is an extension, which is injected by the higher-level module \alib_format and
296/// is accessed through the header file \implude{Format}.
297/// Furthermore, the compiler-symbol \ref ALIB_DEBUG_BOXING has to be set.
298/// @return A string containing the dump.
301
302}; // namespace [alib::boxing::debug]
303
304#include "ALib.Lang.CIMethods.H"
305#endif // ALIB_DEBUG_BOXING
306
const detail::VTable * DbgGetVTable() const
Definition box.inl:386
static ALIB_DLL threads::RecursiveLock DefaultLock
static ALIB_DLL SPFormatter Default
constexpr integer Length() const
Definition string.inl:318
#define ALIB_DLL
Definition alib.inl:496
#define A_CHAR(STR)
#define ALIB_TVALUE(T)
Definition alib.inl:986
#define ALIB_LOCK_RECURSIVE_WITH(lock)
Definition alib.inl:1323
#define ALIB_EXPORT
Definition alib.inl:488
void dumpVTables(AString &result, DbgStringTable< const detail::VTable * > &vtableNames, bool staticVtables, bool includeFunctions)
AString & removeNamespaces(AString &string, integer startIndex)
AString DumpFunctions(const std::vector< std::pair< const std::type_info *, uinteger > > &input, const String &headline, const String &indent)
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 DumpVTables(bool staticVtables, bool includeFunctions)
AString TypeInfo(const Box &box, const String &headline=A_CHAR("Boxing Information For Boxable Type: "), const String &indent=A_CHAR(" "))
void dumpFunctions(const std::vector< std::pair< const std::type_info *, uinteger > > &input, AString &output, const String &headline, const String &indent, DbgStringTable< uinteger > &tmpStrings)
void DumpCustomFunctionHashMapMetrics(AString &target, bool detailedBucketList)
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
constexpr CString NEW_LINE
A zero-terminated string containing the new-line character sequence.
Definition cstring.inl:644
constexpr const String EMPTY_STRING
An empty string of the default character type.
Definition string.inl:2443
monomem::TMonoAllocator< lang::HeapAllocator > MonoAllocator
format::Formatter Formatter
Type alias in namespace alib.
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381
NLocalString< 512 > NString512
Type alias name for TLocalString<nchar,512>.
std::tuple< String, TAssociatedTypes... > ElementType
Shortcut to the std::tuple-type that instantiations of this template class store.
DbgStringTable(MonoAllocator &monoAllocator)
MonoAllocator & allocator
Allocator for making copies of inserted strings.
std::vector< ElementType > Base
Shortcut to the base type of this type.
String & Add(const String &src, TArgs &&... args)
The custom function hash.
Definition vtable.inl:227