Debian Codegraph @

include/deal.II/algorithms/general_data_storage.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 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_algorithms_general_data_storage_h
16 #define dealii_algorithms_general_data_storage_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/exceptions.h>
22
23 #include <boost/core/demangle.hpp>
24
25 #include <algorithm>
26 #include <any>
27 #include <map>
28 #include <ostream>
29 #include <string>
30 #include <typeinfo>
31
32 DEAL_II_NAMESPACE_OPEN
33
34
35 /**
36 * This class facilitates the storage of any general data.
37 * It offers a mechanism to store any amount of data, of any type,
38 * which is then made accessible by an identifier string.
39 *
40 * When using this class, please cite @cite SartoriGiulianiBardelloni-2018-a.
41 */
42 class GeneralDataStorage : public EnableObserverPointer
43 {
44 public:
45 /**
46 * Default constructor.
47 */
48 GeneralDataStorage() = default;
49
50 /**
51 * Copy constructor.
52 */
53 GeneralDataStorage(const GeneralDataStorage &) = default;
54
55 /**
56 * Move constructor.
57 */
58 GeneralDataStorage(GeneralDataStorage &&) = default;
59
60 /**
61 * Number of objects stored by this class instance.
62 */
63 std::size_t
64 size() const;
65
66 /**
67 * Merge the contents of @p other_data with this object.
68 */
69 void
70 merge(const GeneralDataStorage &other_data);
71
72 /**
73 * Print the contents of the internal cache to the @p stream.
74 *
75 * Each key and value pair in the @p any_data map are printed on an
76 * individual line, with the <tt>std::string</tt> key listed first
77 * followed by the demangled <tt>type_id</tt> of the associated mapped
78 * type.
79 */
80 template <class Stream>
81 void
82 print_info(Stream &stream);
83
84 /**
85 * Clear all data stored in this class instance.
86 *
87 * When you call this function, it destroys all objects you asked to be stored
88 * as copies, and it forgets about the references to data you asked to store
89 * by reference. As a consequence, you are now free to destroy the objects to
90 * which references were stored at whatever time you want -- before or after
91 * the current `GeneralDataStorage` object is destroyed.
92 *
93 * To clarify this point, consider the following small example:
94 *
95 * @code
96 * GeneralDataStorage data;
97 *
98 * {
99 * const double some_number = ...;
100 * data.add_unique_reference("value", some_number);
101 *
102 * // Adding either of these next two lines could fix the
103 * // issue, by removing the association of some_number with data:
104 * // data.remove_object_with_name("value");
105 * // data.reset();
106 * } // some_number goes out of scope here
107 *
108 * const double some_other_number
109 * = data.get_object_with_name<double>("value"); // Invalid call
110 * @endcode
111 *
112 * In the code above, the @p data object has a longer scope than
113 * <tt>some_number</tt>. By the time we fetch the <tt>"value"</tt> from
114 * @p data , the reference to @p some_number is no longer valid.
115 *
116 * Similarly, for data copied into a GeneralDataStorage object one should
117 * consider the scope under which it remains valid:
118 *
119 * @code
120 * double* ptr_to_some_number = null_ptr;
121 *
122 * {
123 * GeneralDataStorage data;
124 * const double some_number = ...;
125 * data.add_unique_copy("value", some_number);
126 *
127 * ptr_to_some_number = &(data.get_object_with_name<double>("value"));
128 * } // The copy to some_number goes out of scope here
129 *
130 * const double some_other_number
131 * = *ptr_to_some_number; // Invalid call
132 * @endcode
133 *
134 * Similar to the first example, we must be conscious of the fact that the
135 * copies of any @p Type stored by @p data only remains valid while the
136 * GeneralDataStorage instance in which it is stored is alive.
137 *
138 * Furthermore, as elucidated in the last example, the copy of the
139 * class instance (owned by GeneralDataStorage) that is being pointed to
140 * is no longer alive when the reset() function is called, or when it is
141 * removed via a call to remove_object_with_name().
142 *
143 * @code
144 * GeneralDataStorage data;
145 * double* ptr_to_some_number = null_ptr;
146 *
147 * {
148 * const double some_number = ...;
149 * data.add_unique_copy("value", some_number);
150 *
151 * ptr_to_some_number = &(data.get_object_with_name<double>("value"));
152 *
153 * // The copy to some_number would go out of scope when either of
154 * // following two calls are made:
155 * data.remove_object_with_name("value");
156 * data.reset();
157 * }
158 *
159 * const double some_other_number
160 * = *ptr_to_some_number; // Invalid call
161 * @endcode
162 */
163 void
164 reset();
165
166 /**
167 * @name Data storage and access
168 * @{
169 */
170
171 /**
172 * Store internally a copy of the given object. The copied object is
173 * owned by this class, and is accessible via reference through the
174 * get_object_with_name() method.
175 *
176 * This function ensures that no @p entry with the given @p name is
177 * already stored by this class instance.
178 */
179 template <typename Type>
180 void
181 add_unique_copy(const std::string &name, const Type &entry);
182
183 /**
184 * Store internally a copy of the given object. The copied object is
185 * owned by this class, and is accessible via reference through the
186 * get_object_with_name() method.
187 *
188 * This function does not perform any checks to ensure that the @p entry
189 * with the given @p name is already stored by this class instance. If the
190 * @p name does in fact point to existing data, then this is overwritten.
191 */
192 template <typename Type>
193 void
194 add_or_overwrite_copy(const std::string &name, const Type &entry);
195
196 /**
197 * Add a reference to an already existing object. The object is not
198 * owned by this class, and the user has to guarantee that the
199 * referenced object lives longer than this class instance. The stored
200 * reference is accessible through the get_object_with_name() method.
201 *
202 * This function ensures that no @p entry with the given @p name is
203 * already stored by this class instance.
204 */
205 template <typename Type>
206 void
207 add_unique_reference(const std::string &name, Type &entry);
208
209 /**
210 * Add a reference to an already existing object. The object is not
211 * owned by this class, and the user has to guarantee that the
212 * referenced object lives longer than this class instance. The stored
213 * reference is accessible through the get_object_with_name() method.
214 *
215 * This function does not perform any checks to ensure that the @p entry
216 * with the given @p name is already stored by this class instance. If the
217 * @p name does in fact point to existing data, then this is overwritten.
218 */
219 template <typename Type>
220 void
221 add_or_overwrite_reference(const std::string &name, Type &entry);
222
223 /**
224 * Return a reference to the object with given name. If the object does
225 * not exist, then the input @p arguments will be used to construct an object
226 * of the given @p Type and a reference to this new object then be returned.
227 *
228 * A copy of an object of type @p Type , which is owned by this class
229 * instance, is generated by calling its constructor with the given set of
230 * arguments. For this function, the @p arguments are passed as
231 * <tt>lvalue</tt> references.
232 */
233 template <typename Type, typename Arg, typename... Args>
234 Type &
235 get_or_add_object_with_name(const std::string &name,
236 Arg &argument,
237 Args &...arguments);
238
239 /**
240 * Return a reference to the object with given name. If the object does
241 * not exist, then the input @p arguments will be used to construct an object
242 * of the given @p Type and a reference to this new object then be returned.
243 *
244 * Same as above for a single argument.
245 */
246 template <typename Type, typename Arg>
247 Type &
248 get_or_add_object_with_name(const std::string &name, Arg &argument);
249
250 /**
251 * Return a reference to the object with given name. If the object does
252 * not exist, then the input @p arguments will be used to construct an object
253 * of the given @p Type and a reference to this new object then be returned.
254 *
255 * A copy of an object of type @p Type , which is owned by this class
256 * instance, is generated by calling its constructor with the given set of
257 * arguments. In contrast to the previous function of the same name, for
258 * this function the @p arguments are passed as <tt>rvalue</tt> references.
259 */
260 template <typename Type, typename Arg, typename... Args>
261 Type &
262 get_or_add_object_with_name(const std::string &name,
263 Arg &&argument,
264 Args &&...arguments);
265
266 /**
267 * Return a reference to the object with given name. If the object does
268 * not exist, then the input @p arguments will be used to construct an object
269 * of the given @p Type and a reference to this new object then be returned.
270 *
271 * Same as above for a single argument.
272 */
273 template <typename Type, typename Arg>
274 Type &
275 get_or_add_object_with_name(const std::string &name, Arg &&argument);
276
277 /**
278 * Same as above for default constructors.
279 */
280 template <typename Type>
281 Type &
282 get_or_add_object_with_name(const std::string &name);
283
284 /**
285 * Return a reference to the object with given name.
286 *
287 * This function throws an exception if either an object with the given name
288 * is not stored in this class, or if the object with the given name is
289 * neither of the exact specified @p Type nor a pointer to the @p Type.
290 */
291 template <typename Type>
292 Type &
293 get_object_with_name(const std::string &name);
294
295 /**
296 * Return a constant reference to the object with the given name.
297 *
298 * This function throws an exception if either an object with the given name
299 * is not stored in this class, or if the object with the given name is
300 * neither of the exact specified @p Type nor a pointer to the @p Type.
301 */
302 template <typename Type>
303 const Type &
304 get_object_with_name(const std::string &name) const;
305
306 /**
307 * Find out if we store an object with given name.
308 */
309 bool
310 stores_object_with_name(const std::string &name) const;
311
312 /**
313 * Remove the object with given name.
314 */
315 void
316 remove_object_with_name(const std::string &name);
317
318 /** @} */
319
320 /**
321 * An entry with this name does not exist in the internal std::any map.
322 */
323 DeclException1(ExcNameNotFound,
324 std::string,
325 << "No entry with the name " << arg1 << " exists.");
326
327 /**
328 * An entry with this name does not exist in the internal std::any map.
329 */
330 DeclException1(ExcNameHasBeenFound,
331 std::string,
332 << "An entry with the name " << arg1 << " already exists.");
333
334 /**
335 * The requested type and the stored type are different.
336 */
337 DeclException3(ExcTypeMismatch,
338 std::string,
339 const char *,
340 const char *,
341 << "The stored type for entry with name \"" << arg1 << "\" is "
342 << arg2 << " but you requested type " << arg3 << '.');
343
344 private:
345 /**
346 * Arbitrary user data, identified by a string.
347 */
348 std::map<std::string, std::any> any_data;
349 };
350
351
352 /*----------------- Inline and template methods -----------------*/
353
354
355 #ifndef DOXYGEN
356
357
358 template <class Stream>
359 void
360 GeneralDataStorage::print_info(Stream &os)
361 {
362 for (const auto &it : any_data)
363 {
364 os << it.first << '\t' << '\t'
365 << boost::core::demangle(it.second.type().name()) << std::endl;
366 }
367 }
368
369
370 template <typename Type>
371 void
372 GeneralDataStorage::add_unique_copy(const std::string &name, const Type &entry)
373 {
374 AssertThrow(!stores_object_with_name(name), ExcNameHasBeenFound(name));
375 add_or_overwrite_copy(name, entry);
376 }
377
378
379 template <typename Type>
380 void
381 GeneralDataStorage::add_or_overwrite_copy(const std::string &name,
382 const Type &entry)
383 {
384 any_data[name] = entry;
385 }
386
387
388 template <typename Type>
389 void
390 GeneralDataStorage::add_unique_reference(const std::string &name, Type &entry)
391 {
392 AssertThrow(!stores_object_with_name(name), ExcNameHasBeenFound(name));
393 add_or_overwrite_reference(name, entry);
394 }
395
396
397 template <typename Type>
398 void
399 GeneralDataStorage::add_or_overwrite_reference(const std::string &name,
400 Type &entry)
401 {
402 Type *ptr = &entry;
403 any_data[name] = ptr;
404 }
405
406
407 template <typename Type>
408 Type &
409 GeneralDataStorage::get_object_with_name(const std::string &name)
410 {
411 AssertThrow(stores_object_with_name(name), ExcNameNotFound(name));
412
413 Type *p = nullptr;
414
415 if (any_data[name].type() == typeid(Type *))
416 {
417 p = std::any_cast<Type *>(any_data[name]);
418 }
419 else if (any_data[name].type() == typeid(Type))
420 {
421 p = std::any_cast<Type>(&any_data[name]);
422 }
423 else
424 {
425 AssertThrow(false,
426 ExcTypeMismatch(name,
427 any_data[name].type().name(),
428 typeid(Type).name()));
429 }
430
431 return *p;
432 }
433
434
435 template <typename Type>
436 const Type &
437 GeneralDataStorage::get_object_with_name(const std::string &name) const
438 {
439 AssertThrow(stores_object_with_name(name), ExcNameNotFound(name));
440
441 const auto it = any_data.find(name);
442
443 if (it->second.type() == typeid(Type *))
444 {
445 const Type *p = std::any_cast<Type *>(it->second);
446 return *p;
447 }
448 else if (it->second.type() == typeid(Type))
449 {
450 const Type *p = std::any_cast<Type>(&it->second);
451 return *p;
452 }
453 else
454 {
455 AssertThrow(false,
456 ExcTypeMismatch(name,
457 it->second.type().name(),
458 typeid(Type).name()));
459 const Type *p = nullptr;
460 return *p;
461 }
462 }
463
464
465
466 template <typename Type, typename Arg>
467 Type &
468 GeneralDataStorage::get_or_add_object_with_name(const std::string &name,
469 Arg &argument)
470 {
471 if (!stores_object_with_name(name))
472 add_unique_copy(name, Type(argument));
473
474 return get_object_with_name<Type>(name);
475 }
476
477
478
479 template <typename Type, typename Arg, typename... Args>
480 Type &
481 GeneralDataStorage::get_or_add_object_with_name(const std::string &name,
482 Arg &argument,
483 Args &...arguments)
484 {
485 if (!stores_object_with_name(name))
486 add_unique_copy(name, Type(argument, arguments...));
487
488 return get_object_with_name<Type>(name);
489 }
490
491
492
493 template <typename Type, typename Arg>
494 Type &
495 GeneralDataStorage::get_or_add_object_with_name(const std::string &name,
496 Arg &&argument)
497 {
498 if (!stores_object_with_name(name))
499 add_unique_copy(name, Type(std::forward<Arg>(argument)));
500
501 return get_object_with_name<Type>(name);
502 }
503
504
505
506 template <typename Type, typename Arg, typename... Args>
507 Type &
508 GeneralDataStorage::get_or_add_object_with_name(const std::string &name,
509 Arg &&argument,
510 Args &&...arguments)
511 {
512 if (!stores_object_with_name(name))
513 add_unique_copy(name,
514 Type(std::forward<Arg>(argument),
515 std::forward<Args>(arguments)...));
516
517 return get_object_with_name<Type>(name);
518 }
519
520
521 template <typename Type>
522 Type &
523 GeneralDataStorage::get_or_add_object_with_name(const std::string &name)
524 {
525 if (!stores_object_with_name(name))
526 add_unique_copy(name, Type());
527
528 return get_object_with_name<Type>(name);
529 }
530
531
532 #endif // DOXYGEN
533
534
535 DEAL_II_NAMESPACE_CLOSE
536
537 #endif // dealii_algorithms_general_data_storage_h