Debian Codegraph @

include/deal.II/base/enable_observer_pointer.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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_enable_observer_pointer_h
16 #define dealii_enable_observer_pointer_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <atomic>
24 #include <map>
25 #include <mutex>
26 #include <ostream>
27 #include <string>
28 #include <typeinfo>
29 #include <vector>
30
31 DEAL_II_NAMESPACE_OPEN
32
33
34 // Forward declaration
35 template <typename T, typename P>
36 class ObserverPointer;
37
38
39 /**
40 * This class supports the functioning of the ObserverPointer class.
41 *
42 * Used as a base class, this class allows the ObserverPointer class to register
43 * with an object that it is observing that object. As a consequence, the object
44 * can report an error when its destructor is called if there are still
45 * ObserverPointers pointing to it, since destroying the object would lead to
46 * dangling pointers that point to memory that's no longer valid.
47 *
48 * In actual practice, the mechanism works as follows: Assume you have an
49 * `ObserverPointer<X>` object that points objects of type `X` (where `X` is
50 * derived from EnableObserverPointer). When you write
51 * @code
52 * ObserverPointer<X> ptr;
53 * X object;
54 * ptr = &x;
55 * @endcode
56 * then `ObserverPointer::operator=()` called in the last line of the code above
57 * will call the EnableObserverPointer::subscribe() function (of the class
58 * documented here) with arguments that allow both
59 * sides to track each other. If `object` goes out of scope while `ptr` is still
60 * pointing to it, this would create a dangling pointer, and the destructor of
61 * `X` (i.e., actually the destructor of the EnableObserverPointer base class of
62 * `X`) will abort the program with an error.
63 *
64 * In practice, when such an error happens, it is often difficult to tell
65 * *which* pointer is still pointing to the `object` that is being destroyed. To
66 * this end, ObserverPointer can also pass a string to the subscribe() member
67 * function that identifies which observer is still alive. This string is passed
68 * to the ObserverPointer object upon construction and is user-defined so that
69 * code developed can give names to their observer pointers.
70 *
71 * @ingroup memory
72 */
73 class EnableObserverPointer
74 {
75 public:
76 /**
77 * Constructor setting the counter to zero.
78 */
79 EnableObserverPointer();
80
81 /**
82 * Copy-constructor.
83 *
84 * The counter of the copy is zero, since references point to the original
85 * object.
86 */
87 EnableObserverPointer(const EnableObserverPointer &);
88
89 /**
90 * Move constructor.
91 *
92 * An object inheriting from EnableObserverPointer can only be
93 * moved if no other objects are subscribing to it.
94 */
95 EnableObserverPointer(EnableObserverPointer &&) noexcept;
96
97 /**
98 * Destructor, asserting that the counter is zero.
99 */
100 virtual ~EnableObserverPointer();
101
102 /**
103 * Assignment operator.
104 *
105 * This has to be handled with care, too, because the counter has to remain
106 * the same. It therefore does nothing more than returning <tt>*this</tt>.
107 */
108 EnableObserverPointer &
109 operator=(const EnableObserverPointer &);
110
111 /**
112 * Move assignment operator. Only invalidates the object moved from.
113 */
114 EnableObserverPointer &
115 operator=(EnableObserverPointer &&) noexcept;
116
117 /**
118 * @name Querying the observer pointers an object has.
119 *
120 * @{
121 */
122
123 /**
124 * Return the present number of subscriptions to this object. This allows to
125 * use this class for reference counted lifetime determination where the
126 * last one to unsubscribe also deletes the object.
127 */
128 unsigned int
129 n_subscriptions() const;
130
131 /**
132 * List the subscribers to the input @p stream.
133 */
134 template <typename StreamType>
135 void
136 list_subscribers(StreamType &stream) const;
137
138 /**
139 * List the subscribers to @p deallog.
140 */
141 void
142 list_subscribers() const;
143
144 /** @} */
145
146 /**
147 * @addtogroup Exceptions
148 * @{
149 */
150
151 /**
152 * Exception: Object may not be deleted, since it is used.
153 */
154 DeclException3(ExcInUse,
155 int,
156 std::string,
157 std::string,
158 << "Object of class " << arg2 << " is still used by " << arg1
159 << " other objects."
160 << "\n\n"
161 << "(Additional information: " << arg3 << ")\n\n"
162 << "See the entry in the Frequently Asked Questions of "
163 << "deal.II (linked to from http://www.dealii.org/) for "
164 << "a lot more information on what this error means and "
165 << "how to fix programs in which it happens.");
166
167 /**
168 * A subscriber with the identification string given to
169 * EnableObserverPointer::unsubscribe() did not subscribe to the
170 * object.
171 */
172 DeclException2(ExcNoSubscriber,
173 std::string,
174 std::string,
175 << "No subscriber with identifier <" << arg2
176 << "> subscribes to this object of class " << arg1
177 << ". Consequently, it cannot be unsubscribed.");
178 /** @} */
179
180 /**
181 * Read or write the data of this object to or from a stream for the purpose
182 * of serialization using the [BOOST serialization
183 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
184 *
185 * This function does not actually serialize any of the member variables of
186 * this class. The reason is that what this class stores is only who
187 * subscribes to this object, but who does so at the time of storing the
188 * contents of this object does not necessarily have anything to do with who
189 * subscribes to the object when it is restored. Consequently, we do not
190 * want to overwrite the subscribers at the time of restoring, and then
191 * there is no reason to write the subscribers out in the first place.
192 */
193 template <class Archive>
194 void
195 serialize(Archive &ar, const unsigned int version);
196
197 private:
198 /**
199 * Store the number of objects which subscribed to this object. Initially,
200 * this number is zero, and upon destruction it shall be zero again (i.e.
201 * all objects which subscribed should have unsubscribed again).
202 *
203 * The creator (and owner) of an object is counted in the map below if HE
204 * manages to supply identification.
205 *
206 * We use the <tt>mutable</tt> keyword in order to allow subscription to
207 * constant objects also.
208 *
209 * This counter may be read from and written to concurrently in
210 * multithreaded code: hence we use the <code>std::atomic</code> class
211 * template.
212 */
213 mutable std::atomic<unsigned int> counter;
214
215 /**
216 * In this map, we count subscriptions for each different identification
217 * string supplied to subscribe().
218 */
219 mutable std::map<std::string, unsigned int> counter_map;
220
221 /**
222 * The data type used in #counter_map.
223 */
224 using map_value_type = decltype(counter_map)::value_type;
225
226 /**
227 * The iterator type used in #counter_map.
228 */
229 using map_iterator = decltype(counter_map)::iterator;
230
231 /**
232 * In this vector, we store pointers to the validity bool in the
233 * ObserverPointer objects that subscribe to this class.
234 */
235 mutable std::vector<std::atomic<bool> *> validity_pointers;
236
237 /**
238 * Pointer to the typeinfo object of this object, from which we can later
239 * deduce the class name. Since this information on the derived class is
240 * neither available in the destructor, nor in the constructor, we obtain it
241 * in between and store it here.
242 */
243 mutable const std::type_info *object_info;
244
245 /**
246 * A mutex used to ensure data consistency when accessing the `mutable`
247 * members of this class. This lock is used in the subscribe() and
248 * unsubscribe() functions, as well as in `list_subscribers()`.
249 */
250 static std::mutex mutex;
251
252 /**
253 * @name EnableObserverPointer functionality
254 *
255 * Classes derived from EnableObserverPointer provide a facility
256 * to subscribe to this object. This is mostly used by the ObserverPointer
257 * class.
258 * @{
259 */
260
261 /**
262 * Subscribes a user of the object by storing the pointer @p validity. The
263 * subscriber may be identified by text supplied as @p identifier.
264 */
265 void
266 subscribe(std::atomic<bool> *const validity,
267 const std::string &identifier = "") const;
268
269 /**
270 * Unsubscribes a user from the object.
271 *
272 * @note The @p identifier and the @p validity pointer must be the same as
273 * the one supplied to subscribe().
274 */
275 void
276 unsubscribe(std::atomic<bool> *const validity,
277 const std::string &identifier = "") const;
278
279 /**
280 * Check that there are no objects subscribing to this object. If this check
281 * passes then it is safe to destroy the current object. It this check fails
282 * then this function will either abort or print an error message to deallog
283 * (by using the AssertNothrow mechanism), but will not throw an exception.
284 *
285 * @note Since this function is just a consistency check it does nothing in
286 * release mode.
287 *
288 * @note If this function is called when there is an uncaught exception
289 * then, rather than aborting, this function prints an error message to the
290 * standard error stream and returns.
291 */
292 void
293 check_no_subscribers() const noexcept;
294
295 template <typename, typename>
296 friend class ObserverPointer;
297
298 /** @} */
299 };
300
301
302 /**
303 * A type alias for the EnableObserverPointer class that makes sure
304 * the previous name of the class, Subscriptor, continues to be available.
305 *
306 * @deprecated Use the new name of the class, ObserverPointer, instead.
307 */
308 using Subscriptor DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
309 "Use the new name of the class, EnableObserverPointer.") =
310 EnableObserverPointer;
311
312
313 //---------------------------------------------------------------------------
314
315 inline EnableObserverPointer::EnableObserverPointer()
316 : counter(0)
317 , object_info(nullptr)
318 {}
319
320
321
322 inline EnableObserverPointer::EnableObserverPointer(
323 const EnableObserverPointer &)
324 : counter(0)
325 , object_info(nullptr)
326 {}
327
328
329
330 inline EnableObserverPointer &
331 EnableObserverPointer::operator=(const EnableObserverPointer &s)
332 {
333 object_info = s.object_info;
334 return *this;
335 }
336
337
338
339 inline unsigned int
340 EnableObserverPointer::n_subscriptions() const
341 {
342 return counter;
343 }
344
345
346
347 template <class Archive>
348 inline void
349 EnableObserverPointer::serialize(Archive &, const unsigned int)
350 {
351 // do nothing, as explained in the
352 // documentation of this function
353 }
354
355 template <typename StreamType>
356 inline void
357 EnableObserverPointer::list_subscribers(StreamType &stream) const
358 {
359 std::lock_guard<std::mutex> lock(mutex);
360
361 for (const auto &it : counter_map)
362 stream << it.second << '/' << counter << " subscriptions from \""
363 << it.first << '\"' << std::endl;
364 }
365
366 DEAL_II_NAMESPACE_CLOSE
367
368 #endif