lazy.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 2023 - 2024 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_lazy_h
#define dealii_lazy_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
#include <deal.II/base/memory_consumption.h>
#include <deal.II/base/mutex.h>
 
#include <atomic>
#include <mutex>
#include <optional>
#include <type_traits>
 
 
DEAL_II_NAMESPACE_OPEN
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
class Lazy
{
public:
  Lazy();
 
 
  Lazy(const Lazy &other);
 
 
  Lazy(Lazy &&other) noexcept;
 
 
  Lazy &
  operator=(const Lazy &other);
 
 
  Lazy &
  operator=(Lazy &&other) noexcept;
 
 
  void
  reset() noexcept;
 
 
  template <typename Callable>
  void
  ensure_initialized(const Callable &creator) const
    DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>));
 
 
  bool
  has_value() const;
 
 
  const T &
  value() const;
 
 
  T &
  value();
 
 
  template <typename Callable>
  const T &
  value_or_initialize(const Callable &creator) const
    DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>));
 
 
  template <typename Callable>
  DEAL_II_ALWAYS_INLINE inline T &
  value_or_initialize(const Callable &creator)
    DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>));
 
 
  std::size_t
  memory_consumption() const;
 
private:
  mutable std::optional<T> object;
 
 
  mutable std::atomic<bool> object_is_initialized;
 
 
  mutable Threads::Mutex initialization_mutex;
};
 
// ------------------------------- inline functions --------------------------
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline Lazy<T>::Lazy()
  : object_is_initialized(false)
{}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline Lazy<T>::Lazy(const Lazy &other)
  : object(other.object)
{
  object_is_initialized.store(other.object_is_initialized.load());
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline Lazy<T>::Lazy(Lazy &&other) noexcept
  : object(std::move(other.object))
{
  object_is_initialized.store(other.object_is_initialized.load());
 
  // Mark the other object as uninitialized. This is marginally non-trivial
  // because moving from std::optional<T> does *not* result in an empty
  // std::optional<T> but instead one that does contain a T, but one that
  // has been moved from -- typically something akin to a default-initialized
  // T. That seems undesirable, so reset everything to an empty state.
  other.object_is_initialized.store(false);
  other.object.reset();
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline Lazy<T> &Lazy<T>::operator=(const Lazy &other)
{
  object = other.object;
  object_is_initialized.store(other.object_is_initialized.load());
  return *this;
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline Lazy<T> &Lazy<T>::operator=(Lazy &&other) noexcept
{
  object = std::move(other.object);
  object_is_initialized.store(other.object_is_initialized.load());
 
  // Mark the other object as uninitialized. This is marginally non-trivial
  // because moving from std::optional<T> does *not* result in an empty
  // std::optional<T> but instead one that does contain a T, but one that
  // has been moved from -- typically something akin to a default-initialized
  // T. That seems undesirable, so reset everything to an empty state.
  other.object_is_initialized.store(false);
  other.object.reset();
 
  return *this;
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline void Lazy<T>::reset() noexcept
{
  object_is_initialized.store(false);
  object.reset();
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
template <typename Callable>
inline DEAL_II_ALWAYS_INLINE
  void Lazy<T>::ensure_initialized(const Callable &creator) const
  DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>))
{
  //
  // Use Schmidt's double checking [1] for checking and initializing the
  // object.
  //
  // [1] https://en.wikipedia.org/wiki/Double-checked_locking
  //
 
  //
  // Check the object_is_initialized atomic with "acquire" semantics [1].
  //
  // This ensures that (a) all subsequent reads (of the object) are
  // ordered after this check, and that (b) all writes to the object
  // before the atomic bool was set to true with "release" semantics are
  // visible on this thread.
  //
  // [1]
  // https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering
  //
  if (!object_is_initialized.load(std::memory_order_acquire))
#ifdef DEAL_II_HAVE_CXX20
    [[unlikely]]
#endif
    {
      std::lock_guard<std::mutex> lock(initialization_mutex);
 
      //
      // Check again. If this thread won the race to the lock then we
      // initialize the object. Otherwise another thread has already
      // initialized the object and flipped the object_is_initialized
      // bit. (Here, the initialization_mutex ensures consistent ordering
      // with a memory fence, so we will observe the updated bool without
      // acquire semantics.)
      //
      if (!object_is_initialized.load(std::memory_order_relaxed))
        {
          Assert(object.has_value() == false, ExcInternalError());
          object.emplace(std::move(creator()));
 
          //
          // Flip the object_is_initialized boolean with "release"
          // semantics [1].
          //
          // This ensures that the above move is visible on all threads
          // before checking the atomic bool with acquire semantics.
          //
          object_is_initialized.store(true, std::memory_order_release);
        }
    }
 
  Assert(
    object.has_value(),
    ::ExcMessage(
      "The internal std::optional<T> object does not contain a valid object "
      "even though we have just initialized it."));
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline DEAL_II_ALWAYS_INLINE bool Lazy<T>::has_value() const
{
  //
  // In principle it would be sufficient to solely check the atomic<bool>
  // object_is_initialized because the load() is performed with "acquire"
  // semantics. But just in case let's check the object.has_value() boolean
  // as well:
  //
  return (object_is_initialized && object.has_value());
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline DEAL_II_ALWAYS_INLINE const T &Lazy<T>::value() const
{
  Assert(
    object_is_initialized && object.has_value(),
    ::ExcMessage(
      "value() has been called but the contained object has not been "
      "initialized. Did you forget to call 'ensure_initialized()' first?"));
 
  return object.value();
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
inline DEAL_II_ALWAYS_INLINE T &Lazy<T>::value()
{
  Assert(
    object_is_initialized && object.has_value(),
    ::ExcMessage(
      "value() has been called but the contained object has not been "
      "initialized. Did you forget to call 'ensure_initialized()' first?"));
 
  return object.value();
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
template <typename Callable>
inline DEAL_II_ALWAYS_INLINE const T &Lazy<T>::value_or_initialize(
  const Callable &creator) const
  DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>))
{
  ensure_initialized(creator);
  return object.value();
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
template <typename Callable>
inline DEAL_II_ALWAYS_INLINE T &Lazy<T>::value_or_initialize(
  const Callable &creator)
  DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>))
{
  ensure_initialized(creator);
  return object.value();
}
 
 
template <typename T>
DEAL_II_CXX20_REQUIRES((std::is_move_constructible_v<T> &&
                        std::is_move_assignable_v<T>))
std::size_t Lazy<T>::memory_consumption() const
{
  return MemoryConsumption::memory_consumption(object) + //
         sizeof(*this) - sizeof(object);
}
 
 
DEAL_II_NAMESPACE_CLOSE
#endif