| 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 |