observer_pointer.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 1998 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Part of the source code is dual licensed under Apache-2.0 WITH
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
// governing the source code and code contributions can be found in
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
//
// ------------------------------------------------------------------------
 
#ifndef dealii_observer_pointer_h
#define dealii_observer_pointer_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/exceptions.h>
 
#include <atomic>
#include <string>
#include <typeinfo>
 
DEAL_II_NAMESPACE_OPEN

template <typename T, typename P = void>
class ObserverPointer
{
public:
  ObserverPointer();

  template <class Q>
  ObserverPointer(const ObserverPointer<T, Q> &other);

  ObserverPointer(const ObserverPointer<T, P> &other);

  ObserverPointer(ObserverPointer<T, P> &&other) noexcept;

  ObserverPointer(T *t, const std::string &id);

  ObserverPointer(T *t);

  ~ObserverPointer();

  ObserverPointer<T, P> &
  operator=(T *tt);

  template <class Q>
  ObserverPointer<T, P> &
  operator=(const ObserverPointer<T, Q> &other);

  ObserverPointer<T, P> &
  operator=(const ObserverPointer<T, P> &other);

  ObserverPointer<T, P> &
  operator=(ObserverPointer<T, P> &&other) noexcept;

  DEAL_II_DEPRECATED
  void
  clear();

  operator T *() const;

  T &
  operator*() const;

  T *
  get() const;

  T *
  operator->() const;

  template <class Q>
  void
  swap(ObserverPointer<T, Q> &tt);

  void
  swap(T *&ptr);

  std::size_t
  memory_consumption() const;
 
private:
  T *pointer;

  const std::string id;

  std::atomic<bool> pointed_to_object_is_alive;
};
 

template <typename T, typename P = void>
using SmartPointer DEAL_II_DEPRECATED_EARLY_WITH_COMMENT(
  "Use the new name of the class, ObserverPointer.") = ObserverPointer<T, P>;
 
 
/* --------------------- inline Template functions ------------------------- */
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::ObserverPointer()
  : pointer(nullptr)
  , id(typeid(P).name())
  , pointed_to_object_is_alive(false)
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::ObserverPointer(T *t)
  : pointer(t)
  , id(typeid(P).name())
  , pointed_to_object_is_alive(false)
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
 
  if (t != nullptr)
    t->subscribe(&pointed_to_object_is_alive, id);
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::ObserverPointer(T *t, const std::string &id)
  : pointer(t)
  , id(id)
  , pointed_to_object_is_alive(false)
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
 
  if (pointer != nullptr)
    pointer->subscribe(&pointed_to_object_is_alive, id);
}
 
 
 
template <typename T, typename P>
template <class Q>
inline ObserverPointer<T, P>::ObserverPointer(
  const ObserverPointer<T, Q> &other)
  : pointer(other.pointer)
  , id(other.id)
  , pointed_to_object_is_alive(false)
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
 
  if (other != nullptr)
    {
      Assert(other.pointed_to_object_is_alive,
             ExcMessage("You can't copy a smart pointer object that "
                        "is pointing to an object that is no longer alive."));
      pointer->subscribe(&pointed_to_object_is_alive, id);
    }
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::ObserverPointer(
  const ObserverPointer<T, P> &other)
  : pointer(other.pointer)
  , id(other.id)
  , pointed_to_object_is_alive(false)
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
 
  if (other != nullptr)
    {
      Assert(other.pointed_to_object_is_alive,
             ExcMessage("You can't copy a smart pointer object that "
                        "is pointing to an object that is no longer alive."));
      pointer->subscribe(&pointed_to_object_is_alive, id);
    }
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::ObserverPointer(
  ObserverPointer<T, P> &&other) noexcept
  : pointer(other.pointer)
  , id(other.id)
  , pointed_to_object_is_alive(false)
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
 
  if (other != nullptr)
    {
      Assert(other.pointed_to_object_is_alive,
             ExcMessage("You can't move a smart pointer object that "
                        "is pointing to an object that is no longer alive."));
 
      try
        {
          pointer->subscribe(&pointed_to_object_is_alive, id);
        }
      catch (...)
        {
          Assert(false,
                 ExcMessage(
                   "Calling subscribe() failed with an exception, but we "
                   "are in a function that cannot throw exceptions. "
                   "Aborting the program here."));
        }
 
      // Release the rhs object as if we had moved all members away from
      // it directly:
      other = nullptr;
    }
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::~ObserverPointer()
{
  static_assert(std::is_base_of_v<EnableObserverPointer, T>,
                "This class can only be used if the first template argument "
                "is a class derived from 'EnableObserverPointer'.");
 
  if (pointed_to_object_is_alive && pointer != nullptr)
    pointer->unsubscribe(&pointed_to_object_is_alive, id);
}
 
 
 
template <typename T, typename P>
inline void
ObserverPointer<T, P>::clear()
{
  if (pointed_to_object_is_alive && pointer != nullptr)
    {
      pointer->unsubscribe(&pointed_to_object_is_alive, id);
      delete pointer;
      Assert(pointed_to_object_is_alive == false, ExcInternalError());
    }
  pointer = nullptr;
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P> &
ObserverPointer<T, P>::operator=(T *tt)
{
  // optimize if no real action is requested
  if (pointer == tt)
    return *this;
 
  // Let us unsubscribe from the current object
  if (pointed_to_object_is_alive && pointer != nullptr)
    pointer->unsubscribe(&pointed_to_object_is_alive, id);
 
  // Then reset to the new object, and subscribe to it
  pointer = tt;
  if (tt != nullptr)
    pointer->subscribe(&pointed_to_object_is_alive, id);
 
  return *this;
}
 
 
 
template <typename T, typename P>
template <class Q>
inline ObserverPointer<T, P> &
ObserverPointer<T, P>::operator=(const ObserverPointer<T, Q> &other)
{
  // if objects on the left and right
  // hand side of the operator= are
  // the same, then this is a no-op
  if (&other == this)
    return *this;
 
  // Let us unsubscribe from the current object
  if (pointed_to_object_is_alive && pointer != nullptr)
    pointer->unsubscribe(&pointed_to_object_is_alive, id);
 
  // Then reset to the new object, and subscribe to it
  pointer = (other != nullptr ? other.get() : nullptr);
  if (other != nullptr)
    {
      Assert(other.pointed_to_object_is_alive,
             ExcMessage("You can't copy a smart pointer object that "
                        "is pointing to an object that is no longer alive."));
      pointer->subscribe(&pointed_to_object_is_alive, id);
    }
  return *this;
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P> &
ObserverPointer<T, P>::operator=(const ObserverPointer<T, P> &other)
{
  // if objects on the left and right
  // hand side of the operator= are
  // the same, then this is a no-op
  if (&other == this)
    return *this;
 
  // Let us unsubscribe from the current object
  if (pointed_to_object_is_alive && pointer != nullptr)
    pointer->unsubscribe(&pointed_to_object_is_alive, id);
 
  // Then reset to the new object, and subscribe to it
  pointer = (other != nullptr ? other.get() : nullptr);
  if (other != nullptr)
    {
      Assert(other.pointed_to_object_is_alive,
             ExcMessage("You can't copy a smart pointer object that "
                        "is pointing to an object that is no longer alive."));
      pointer->subscribe(&pointed_to_object_is_alive, id);
    }
  return *this;
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P> &
ObserverPointer<T, P>::operator=(ObserverPointer<T, P> &&other) noexcept
{
  if (other == nullptr)
    {
      *this = nullptr;
    }
  // if objects on the left and right hand side of the operator= are
  // the same, then this is a no-op
  else if (&other != this)
    {
      // Let us unsubscribe from the current object
      if (pointer != nullptr && pointed_to_object_is_alive)
        pointer->unsubscribe(&pointed_to_object_is_alive, id);
 
      // Then reset to the new object, and subscribe to it:
      Assert(other.pointed_to_object_is_alive,
             ExcMessage("You can't move a smart pointer object that "
                        "is pointing to an object that is no longer alive."));
      pointer = other.get();
      try
        {
          pointer->subscribe(&pointed_to_object_is_alive, id);
        }
      catch (...)
        {
          Assert(false,
                 ExcMessage(
                   "Calling subscribe() failed with an exception, but we "
                   "are in a function that cannot throw exceptions. "
                   "Aborting the program here."));
        }
 
      // Finally release the rhs object since we moved its contents
      other = nullptr;
    }
  return *this;
}
 
 
 
template <typename T, typename P>
inline ObserverPointer<T, P>::operator T *() const
{
  return pointer;
}
 
 
 
template <typename T, typename P>
inline T &
ObserverPointer<T, P>::operator*() const
{
  Assert(pointer != nullptr, ExcNotInitialized());
  Assert(pointed_to_object_is_alive,
         ExcMessage("The object pointed to is not valid anymore."));
  return *pointer;
}
 
 
 
template <typename T, typename P>
inline T *
ObserverPointer<T, P>::get() const
{
  Assert(pointer != nullptr, ExcNotInitialized());
  Assert(pointed_to_object_is_alive,
         ExcMessage("The object pointed to is not valid anymore."));
  return pointer;
}
 
 
 
template <typename T, typename P>
inline T *
ObserverPointer<T, P>::operator->() const
{
  return this->get();
}
 
 
 
template <typename T, typename P>
template <class Q>
inline void
ObserverPointer<T, P>::swap(ObserverPointer<T, Q> &other)
{
  if constexpr (running_in_debug_mode())
    {
      ObserverPointer<T, P> aux(pointer, id);
      *this = other;
      other = aux;
    }
  else
    {
      std::swap(pointer, other.pointer);
    }
}
 
 
 
template <typename T, typename P>
inline void
ObserverPointer<T, P>::swap(T *&ptr)
{
  if (pointed_to_object_is_alive && pointer != nullptr)
    pointer->unsubscribe(pointed_to_object_is_alive, id);
 
  std::swap(pointer, ptr);
 
  if (pointer != nullptr)
    pointer->subscribe(pointed_to_object_is_alive, id);
}
 
 
 
template <typename T, typename P>
inline std::size_t
ObserverPointer<T, P>::memory_consumption() const
{
  return sizeof(ObserverPointer<T, P>);
}
 
 
 
// The following function is not strictly necessary but is an optimization
// for places where you call swap(p1,p2) with ObserverPointer objects p1, p2.
// Unfortunately, MS Visual Studio (at least up to the 2013 edition) trips
// over it when calling std::swap(v1,v2) where v1,v2 are std::vectors of
// ObserverPointer objects: it can't determine whether it should call std::swap
// or ::swap on the individual elements (see bug #184 on our Google Code
// site. Consequently, just take this function out of the competition for this
// compiler.
#ifndef _MSC_VER
template <typename T, typename P, class Q>
inline void
swap(ObserverPointer<T, P> &t1, ObserverPointer<T, Q> &t2)
{
  t1.swap(t2);
}
#endif
 

template <typename T, typename P>
inline void
swap(ObserverPointer<T, P> &t1, T *&t2)
{
  t1.swap(t2);
}
 
 

template <typename T, typename P>
inline void
swap(T *&t1, ObserverPointer<T, P> &t2)
{
  t2.swap(t1);
}
 
DEAL_II_NAMESPACE_CLOSE
 
#endif