From: Wolfgang Bangerth Date: Wed, 11 Sep 2024 22:46:16 +0000 (-0600) Subject: Make the old class name available as an alias. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dd45de606ce09618ecd8571d80e70d5ee71ac03b;p=dealii.git Make the old class name available as an alias. --- diff --git a/include/deal.II/base/subscriptor.h b/include/deal.II/base/subscriptor.h index 1b2865d2a5..21b43eeeb2 100644 --- a/include/deal.II/base/subscriptor.h +++ b/include/deal.II/base/subscriptor.h @@ -18,316 +18,20 @@ #include -#include +#include -#include -#include -#include -#include -#include -#include DEAL_II_NAMESPACE_OPEN /** - * Handling of subscriptions. + * A type alias for the EnableRefCountingByObserverPointer class that makes sure + * the previous name of the class, Subscriptor, continues to be available. * - * This class, as a base class, allows to keep track of other objects using a - * specific object. It is used to avoid that pointers that point to an object of - * a class derived from EnableRefCountingByObserverPointer are referenced after - * that object has been invalidated. Here, invalidation is assumed to happen - * when the object is moved from or destroyed. The mechanism works as follows: - * The member function subscribe() accepts a pointer to a boolean that is - * modified on invalidation. The object that owns this pointer (usually an - * object of class type ObserverPointer) is then expected to check the state of - * the boolean before trying to access this class. - * - * The utility of this class is even enhanced by providing identifying strings - * to the functions subscribe() and unsubscribe(). These strings are represented - * as const char pointers since the underlying buffer comes from - * (and is managed by) the run-time type information system: more exactly, these - * pointers are the result the function call typeid(x).name() where - * x is some object. Therefore, the pointers provided to - * subscribe() and to unsubscribe() must be the same. Strings with equal - * contents will not be recognized to be the same. The handling in - * ObserverPointer will take care of this. - * The current subscribers to this class can be obtained by calling - * list_subscribers(). - * - * @ingroup memory + * @deprecated Use the new name of the class, ObserverPointer, instead. */ -class EnableRefCountingByObserverPointer -{ -public: - /** - * Constructor setting the counter to zero. - */ - EnableRefCountingByObserverPointer(); - - /** - * Copy-constructor. - * - * The counter of the copy is zero, since references point to the original - * object. - */ - EnableRefCountingByObserverPointer( - const EnableRefCountingByObserverPointer &); - - /** - * Move constructor. - * - * An object inheriting from EnableRefCountingByObserverPointer can only be - * moved if no other objects are subscribing to it. - */ - EnableRefCountingByObserverPointer( - EnableRefCountingByObserverPointer &&) noexcept; - - /** - * Destructor, asserting that the counter is zero. - */ - virtual ~EnableRefCountingByObserverPointer(); - - /** - * Assignment operator. - * - * This has to be handled with care, too, because the counter has to remain - * the same. It therefore does nothing more than returning *this. - */ - EnableRefCountingByObserverPointer & - operator=(const EnableRefCountingByObserverPointer &); - - /** - * Move assignment operator. Only invalidates the object moved from. - */ - EnableRefCountingByObserverPointer & - operator=(EnableRefCountingByObserverPointer &&) noexcept; - - /** - * @name EnableRefCountingByObserverPointer functionality - * - * Classes derived from EnableRefCountingByObserverPointer provide a facility - * to subscribe to this object. This is mostly used by the ObserverPointer - * class. - * @{ - */ - - /** - * Subscribes a user of the object by storing the pointer @p validity. The - * subscriber may be identified by text supplied as @p identifier. - */ - void - subscribe(std::atomic *const validity, - const std::string &identifier = "") const; - - /** - * Unsubscribes a user from the object. - * - * @note The @p identifier and the @p validity pointer must be the same as - * the one supplied to subscribe(). - */ - void - unsubscribe(std::atomic *const validity, - const std::string &identifier = "") const; - - /** - * Return the present number of subscriptions to this object. This allows to - * use this class for reference counted lifetime determination where the - * last one to unsubscribe also deletes the object. - */ - unsigned int - n_subscriptions() const; - - /** - * List the subscribers to the input @p stream. - */ - template - void - list_subscribers(StreamType &stream) const; - - /** - * List the subscribers to @p deallog. - */ - void - list_subscribers() const; - - /** @} */ - - /** - * @addtogroup Exceptions - * @{ - */ - - /** - * Exception: Object may not be deleted, since it is used. - */ - DeclException3(ExcInUse, - int, - std::string, - std::string, - << "Object of class " << arg2 << " is still used by " << arg1 - << " other objects." - << "\n\n" - << "(Additional information: " << arg3 << ")\n\n" - << "See the entry in the Frequently Asked Questions of " - << "deal.II (linked to from http://www.dealii.org/) for " - << "a lot more information on what this error means and " - << "how to fix programs in which it happens."); - - /** - * A subscriber with the identification string given to - * EnableRefCountingByObserverPointer::unsubscribe() did not subscribe to the - * object. - */ - DeclException2(ExcNoSubscriber, - std::string, - std::string, - << "No subscriber with identifier <" << arg2 - << "> subscribes to this object of class " << arg1 - << ". Consequently, it cannot be unsubscribed."); - /** @} */ - - /** - * Read or write the data of this object to or from a stream for the purpose - * of serialization using the [BOOST serialization - * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). - * - * This function does not actually serialize any of the member variables of - * this class. The reason is that what this class stores is only who - * subscribes to this object, but who does so at the time of storing the - * contents of this object does not necessarily have anything to do with who - * subscribes to the object when it is restored. Consequently, we do not - * want to overwrite the subscribers at the time of restoring, and then - * there is no reason to write the subscribers out in the first place. - */ - template - void - serialize(Archive &ar, const unsigned int version); - -private: - /** - * Store the number of objects which subscribed to this object. Initially, - * this number is zero, and upon destruction it shall be zero again (i.e. - * all objects which subscribed should have unsubscribed again). - * - * The creator (and owner) of an object is counted in the map below if HE - * manages to supply identification. - * - * We use the mutable keyword in order to allow subscription to - * constant objects also. - * - * This counter may be read from and written to concurrently in - * multithreaded code: hence we use the std::atomic class - * template. - */ - mutable std::atomic counter; - - /** - * In this map, we count subscriptions for each different identification - * string supplied to subscribe(). - */ - mutable std::map counter_map; - - /** - * The data type used in #counter_map. - */ - using map_value_type = decltype(counter_map)::value_type; - - /** - * The iterator type used in #counter_map. - */ - using map_iterator = decltype(counter_map)::iterator; - - /** - * In this vector, we store pointers to the validity bool in the - * ObserverPointer objects that subscribe to this class. - */ - mutable std::vector *> validity_pointers; - - /** - * Pointer to the typeinfo object of this object, from which we can later - * deduce the class name. Since this information on the derived class is - * neither available in the destructor, nor in the constructor, we obtain it - * in between and store it here. - */ - mutable const std::type_info *object_info; - - /** - * Check that there are no objects subscribing to this object. If this check - * passes then it is safe to destroy the current object. It this check fails - * then this function will either abort or print an error message to deallog - * (by using the AssertNothrow mechanism), but will not throw an exception. - * - * @note Since this function is just a consistency check it does nothing in - * release mode. - * - * @note If this function is called when there is an uncaught exception - * then, rather than aborting, this function prints an error message to the - * standard error stream and returns. - */ - void - check_no_subscribers() const noexcept; - - /** - * A mutex used to ensure data consistency when accessing the `mutable` - * members of this class. This lock is used in the subscribe() and - * unsubscribe() functions, as well as in `list_subscribers()`. - */ - static std::mutex mutex; -}; - -//--------------------------------------------------------------------------- - -inline EnableRefCountingByObserverPointer::EnableRefCountingByObserverPointer() - : counter(0) - , object_info(nullptr) -{} - - - -inline EnableRefCountingByObserverPointer::EnableRefCountingByObserverPointer( - const EnableRefCountingByObserverPointer &) - : counter(0) - , object_info(nullptr) -{} - - - -inline EnableRefCountingByObserverPointer & -EnableRefCountingByObserverPointer::operator=( - const EnableRefCountingByObserverPointer &s) -{ - object_info = s.object_info; - return *this; -} - - - -inline unsigned int -EnableRefCountingByObserverPointer::n_subscriptions() const -{ - return counter; -} - - - -template -inline void -EnableRefCountingByObserverPointer::serialize(Archive &, const unsigned int) -{ - // do nothing, as explained in the - // documentation of this function -} - -template -inline void -EnableRefCountingByObserverPointer::list_subscribers(StreamType &stream) const -{ - std::lock_guard lock(mutex); - - for (const auto &it : counter_map) - stream << it.second << '/' << counter << " subscriptions from \"" - << it.first << '\"' << std::endl; -} +using Subscriptor DEAL_II_DEPRECATED_EARLY_WITH_COMMENT( + "Use the new name of the class, EnableRefCountingByObserverPointer.") = + EnableRefCountingByObserverPointer; DEAL_II_NAMESPACE_CLOSE