Debian Codegraph @

include/deal.II/base/memory_consumption.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2000 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_memory_consumption_h
16 #define dealii_memory_consumption_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/vectorization.h>
22
23 #include <array>
24 #include <complex>
25 #include <cstddef>
26 #include <cstring>
27 #include <memory>
28 #include <optional>
29 #include <string>
30 #include <type_traits>
31 #include <vector>
32
33 DEAL_II_NAMESPACE_OPEN
34
35 /**
36 * This namespace provides functions helping to determine the amount of memory
37 * used by objects. The goal is not necessarily to give the amount of memory
38 * used up to the last bit (what is the memory used by a <tt>std::map</tt>
39 * object?), but rather to aid in the search for memory bottlenecks.
40 *
41 * This namespace has a single member function memory_consumption() and a lot
42 * of specializations. Depending on the argument type of the function, there
43 * are several modes of operation:
44 *
45 * <ol>
46 * <li> If the argument is a fundamental C++ data type (such as <tt>bool</tt>,
47 * <tt>float</tt>, <tt>double</tt> or any of the integer types), then
48 * memory_consumption() just returns <tt>sizeof</tt> of its argument. The
49 * library also provides an estimate for the amount of memory occupied by a
50 * <tt>std::string</tt>.
51 *
52 * <li> For objects, which are neither standard types, nor vectors,
53 * memory_consumption() will simply call the member function of same name. It
54 * is up to the implementation of the data type to provide a good estimate of
55 * the amount of memory used. Inside this function, the use of
56 * MemoryConsumption::memory_consumption() for compounds of the class helps to
57 * obtain this estimate. Most classes in the deal.II library have such a
58 * member function.
59 *
60 * <li> For vectors and C++ arrays of objects, memory_consumption()
61 * recursively calls itself for all entries and adds the results to the size
62 * of the object itself. Some optimized specializations for standard data
63 * types exist.
64 *
65 * <li> For vectors of regular pointers, memory_consumption(T*) returns the
66 * size of the vector of pointers, ignoring the size of the objects.
67 *
68 * </ol>
69 *
70 * <h3>Extending this namespace</h3>
71 *
72 * The function in this namespace and the functionality provided by it relies
73 * on the assumption that there is either a function
74 * <tt>memory_consumption(T)</tt> in this namespace determining the amount of
75 * memory used by objects of type <tt>T</tt> or that the class <tt>T</tt> has
76 * a member function of that name. While the latter is true for almost all
77 * classes in deal.II, we have only implemented the first kind of functions
78 * for the most common data types, such as fundamental types, strings, C++
79 * vectors, C-style arrays, and C++ pairs. These functions therefore do not
80 * cover, for example, C++ maps, lists, etc. If you need such functions feel
81 * free to implement them and send them to us for inclusion.
82 *
83 * @ingroup memory
84 * Wells
85 */
86 namespace MemoryConsumption
87 {
88 /**
89 * Calculate the memory consumption of a fundamental type. See
90 * EnableIfScalar for a discussion on how this restriction (SFINAE) is
91 * implemented.
92 */
93 template <typename T>
94 inline std::enable_if_t<std::is_fundamental_v<T>, std::size_t>
95 memory_consumption(const T &t);
96
97 /**
98 * Estimate the memory consumption of an object. If no further template
99 * specialization (past this one) is available for the type <tt>T</tt>, then
100 * this function returns the member function
101 * <tt>t.memory_consumption()</tt>'s value.
102 */
103 template <typename T>
104 inline std::enable_if_t<!(std::is_fundamental_v<T> || std::is_pointer_v<T>),
105 std::size_t>
106 memory_consumption(const T &t);
107
108 /**
109 * Determine the amount of memory consumed by a C-style string. The returned
110 * value does not include the size of the pointer. This function only
111 * measures up to (and including) the NUL byte; the underlying buffer may be
112 * larger.
113 */
114 inline std::size_t
115 memory_consumption(const char *string);
116
117 /**
118 * Determine the amount of memory in bytes consumed by a
119 * <tt>std::complex</tt> variable.
120 */
121 template <typename T>
122 inline std::size_t
123 memory_consumption(const std::complex<T> &);
124
125 /**
126 * Determine the amount of memory in bytes consumed by a
127 * <tt>VectorizedArray</tt> variable.
128 */
129 template <typename T, std::size_t width>
130 inline std::size_t
131 memory_consumption(const VectorizedArray<T, width> &);
132
133 /**
134 * Determine an estimate of the amount of memory in bytes consumed by a
135 * <tt>std::string</tt> variable.
136 */
137 inline std::size_t
138 memory_consumption(const std::string &s);
139
140 /**
141 * Determine the amount of memory in bytes consumed by a
142 * <tt>std::vector</tt> of elements of type <tt>T</tt> by
143 * calling memory_consumption() for each entry.
144 *
145 * This function loops over all entries of the vector and determines their
146 * sizes using memory_consumption() for each <tt>v[i]</tt>. If the entries
147 * are of constant size, there might be another global function
148 * memory_consumption() for this data type or if there is a member function
149 * of that class of that names that returns a constant value and the
150 * compiler will unroll this loop so that the operation is fast. If the size
151 * of the data elements is variable, for example if they do memory
152 * allocation themselves, then the operation will necessarily be more
153 * expensive.
154 *
155 * Using the algorithm, in particular the loop over all elements, it is
156 * possible to also compute the memory consumption of vectors of vectors,
157 * vectors of strings, etc, where the individual elements may have vastly
158 * different sizes.
159 *
160 * Note that this algorithm also takes into account the size of elements
161 * that are allocated by this vector but not currently used.
162 *
163 * For the most commonly used vectors, there are special functions that
164 * compute the size without a loop. This also applies for the special case
165 * of vectors of bools.
166 */
167 template <typename T>
168 inline std::size_t
169 memory_consumption(const std::vector<T> &v);
170
171 /**
172 * Determine the amount of memory in bytes consumed by a
173 * <tt>std::array</tt> of <tt>N</tt> elements of type <tt>T</tt> by
174 * calling memory_consumption() for each entry.
175 *
176 * This function loops over all entries of the array and determines their
177 * sizes using memory_consumption() for each <tt>v[i]</tt>. If the entries
178 * are of constant size, there might be another global function
179 * memory_consumption() for this data type or if there is a member function
180 * of that class of that names that returns a constant value and the
181 * compiler will unroll this loop so that the operation is fast. If the size
182 * of the data elements is variable, for example if they do memory
183 * allocation themselves, then the operation will necessarily be more
184 * expensive.
185 *
186 * Using the algorithm, in particular the loop over all elements, it is
187 * possible to also compute the memory consumption of arrays of vectors,
188 * arrays of strings, etc, where the individual elements may have vastly
189 * different sizes.
190 */
191 template <typename T, std::size_t N>
192 inline std::size_t
193 memory_consumption(const std::array<T, N> &v);
194
195 /**
196 * Estimate the amount of memory (in bytes) occupied by a C-style array.
197 * Since in this library we do not usually store simple data elements like
198 * <tt>double</tt>s in such arrays (but rather use <tt>std::vector</tt>s or
199 * deal.II <tt>Vector</tt> objects), we do not provide specializations like
200 * for the <tt>std::vector</tt> arrays, but always use the loop over all
201 * elements.
202 */
203 template <typename T, int N>
204 inline std::size_t
205 memory_consumption(const T (&v)[N]);
206
207 /**
208 * Specialization of the determination of the memory consumption of a
209 * vector, here for a vector of <tt>bool</tt>s.
210 *
211 * This is a special case, as the bools are not stored one-by-one, but as a
212 * bit field.
213 */
214 inline std::size_t
215 memory_consumption(const std::vector<bool> &v);
216
217 /**
218 * Determine an estimate of the amount of memory in bytes consumed by a pair
219 * of values.
220 */
221 template <typename A, typename B>
222 inline std::size_t
223 memory_consumption(const std::pair<A, B> &p);
224
225 /**
226 * Determine an estimate of the amount of memory in bytes consumed by a
227 * value wrapped in a std::optional.
228 */
229 template <typename A>
230 inline std::size_t
231 memory_consumption(const std::optional<A> &o);
232
233 /**
234 * Calculate the memory consumption of a pointer.
235 *
236 * @note This function is overloaded for C-style strings; see the
237 * documentation of that function for that case.
238 *
239 * @note This returns the size of the pointer, not the size of the object
240 * pointed to.
241 */
242 template <typename T>
243 inline std::size_t
244 memory_consumption(const T *const);
245
246 /**
247 * Return the amount of memory used by a shared pointer.
248 *
249 * @note This returns the size of the pointer, not of the object pointed to.
250 */
251 template <typename T>
252 inline std::size_t
253 memory_consumption(const std::shared_ptr<T> &);
254
255 /**
256 * Return the amount of memory used by a std::unique_ptr object.
257 *
258 * @note This returns the size of the pointer, not of the object pointed to.
259 */
260 template <typename T>
261 inline std::size_t
262 memory_consumption(const std::unique_ptr<T> &);
263 } // namespace MemoryConsumption
264
265
266
267 // now comes the implementation of these functions
268
269 namespace MemoryConsumption
270 {
271 template <typename T>
272 inline std::enable_if_t<std::is_fundamental_v<T>, std::size_t>
273 memory_consumption(const T &)
274 {
275 return sizeof(T);
276 }
277
278
279
280 inline std::size_t
281 memory_consumption(const char *string)
282 {
283 if (string == nullptr)
284 {
285 return 0;
286 }
287 else
288 {
289 return sizeof(char) * (std::strlen(string) /*Remember the NUL*/ + 1);
290 }
291 }
292
293
294
295 template <typename T>
296 inline std::size_t
297 memory_consumption(const std::complex<T> &)
298 {
299 return sizeof(std::complex<T>);
300 }
301
302
303
304 template <typename T, std::size_t width>
305 inline std::size_t
306 memory_consumption(const VectorizedArray<T, width> &)
307 {
308 return sizeof(VectorizedArray<T, width>);
309 }
310
311
312
313 inline std::size_t
314 memory_consumption(const std::string &s)
315 {
316 return sizeof(s) + s.size();
317 }
318
319
320
321 template <typename T>
322 std::size_t
323 memory_consumption(const std::vector<T> &v)
324 {
325 // shortcut for types that do not allocate memory themselves
326 if (std::is_fundamental_v<T> || std::is_pointer_v<T>)
327 {
328 return v.capacity() * sizeof(T) + sizeof(v);
329 }
330 else
331 {
332 std::size_t mem = sizeof(std::vector<T>);
333 for (unsigned int i = 0; i < v.size(); ++i)
334 {
335 mem += memory_consumption(v[i]);
336 }
337 mem += (v.capacity() - v.size()) * sizeof(T);
338 return mem;
339 }
340 }
341
342
343
344 template <typename T, std::size_t N>
345 std::size_t
346 memory_consumption(const std::array<T, N> &v)
347 {
348 // shortcut for types that do not allocate memory themselves
349 if (std::is_fundamental_v<T> || std::is_pointer_v<T>)
350 {
351 return sizeof(v);
352 }
353 else
354 {
355 std::size_t mem = 0;
356 for (std::size_t i = 0; i != N; ++i)
357 mem += memory_consumption(v[i]);
358 return mem;
359 }
360 }
361
362
363
364 template <typename T, int N>
365 std::size_t
366 memory_consumption(const T (&v)[N])
367 {
368 std::size_t mem = 0;
369 for (unsigned int i = 0; i < N; ++i)
370 mem += memory_consumption(v[i]);
371 return mem;
372 }
373
374
375
376 inline std::size_t
377 memory_consumption(const std::vector<bool> &v)
378 {
379 return v.capacity() / 8 + sizeof(v);
380 }
381
382
383
384 template <typename A, typename B>
385 inline std::size_t
386 memory_consumption(const std::pair<A, B> &p)
387 {
388 return (memory_consumption(p.first) + memory_consumption(p.second));
389 }
390
391
392
393 template <typename A>
394 inline std::size_t
395 memory_consumption(const std::optional<A> &o)
396 {
397 if (o.has_value())
398 {
399 //
400 // If the optional carries a value then we query the contained
401 // value for memory consumption and estimate the size of the
402 // control overhead.
403 //
404 return memory_consumption(o.value()) + sizeof(o) - sizeof(A);
405 }
406 else
407 {
408 //
409 // The optional contains no value, so simply return its plain size
410 // (consisting of space for the value and control overhead):
411 //
412 return sizeof(o);
413 }
414 }
415
416
417
418 template <typename T>
419 inline std::size_t
420 memory_consumption(const T *const)
421 {
422 return sizeof(T *);
423 }
424
425
426
427 template <typename T>
428 inline std::size_t
429 memory_consumption(const std::shared_ptr<T> &)
430 {
431 return sizeof(std::shared_ptr<T>);
432 }
433
434
435
436 template <typename T>
437 inline std::size_t
438 memory_consumption(const std::unique_ptr<T> &)
439 {
440 return sizeof(std::unique_ptr<T>);
441 }
442
443
444
445 template <typename T>
446 inline std::enable_if_t<!(std::is_fundamental_v<T> || std::is_pointer_v<T>),
447 std::size_t>
448 memory_consumption(const T &t)
449 {
450 return t.memory_consumption();
451 }
452 } // namespace MemoryConsumption
453
454 DEAL_II_NAMESPACE_CLOSE
455
456 #endif