thread_local_storage.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 2011 - 2024 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_thread_local_storage_h
#  define dealii_thread_local_storage_h
 
 
#  include <deal.II/base/config.h>
 
#  include <deal.II/base/exceptions.h>
 
#  include <list>
#  include <map>
#  include <memory>
#  include <mutex>
#  include <optional>
#  include <shared_mutex>
#  include <thread>
#  include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
#  ifndef DOXYGEN
class LogStream;
#  endif
 
namespace Threads
{
#  ifndef DOXYGEN
  namespace internal
  {
    /*
     * Workaround: The standard unfortunately has an unfortunate design
     * "flaw" in the std::is_copy_constructible type trait
     * when it comes to STL containers and containing non-copyable objects
     * T. The type trait is true even though any attempted invocation leads
     * to a compilation error. Work around this issue by unpacking some
     * commonly used containers:
     */
    template <typename T>
    struct unpack_container
    {
      using type = T;
    };
 
    template <typename T, typename A>
    struct unpack_container<std::vector<T, A>>
    {
      using type = T;
    };
 
    template <typename T, typename A>
    struct unpack_container<std::list<T, A>>
    {
      using type = T;
    };
  } // namespace internal
#  endif
 
  template <typename T>
  class ThreadLocalStorage
  {
    static_assert(
      std::is_copy_constructible_v<
        typename internal::unpack_container<T>::type> ||
        std::is_default_constructible_v<T>,
      "The stored type must be either copyable, or default constructible");
 
  public:
    ThreadLocalStorage() = default;
 
    ThreadLocalStorage(const ThreadLocalStorage &);
 
    ThreadLocalStorage(ThreadLocalStorage &&t) noexcept;
 
    explicit ThreadLocalStorage(const T &t);
 
    explicit ThreadLocalStorage(T &&t);
 
    ThreadLocalStorage &
    operator=(const ThreadLocalStorage &t);
 
    ThreadLocalStorage &
    operator=(ThreadLocalStorage &&t) noexcept;
 
    T &
    get();
 
    T &
    get(bool &exists);
 
    std::optional<T>
    get_for_thread(const std::thread::id &id) const;
 
    operator T &();
 
    ThreadLocalStorage<T> &
    operator=(const T &t);
 
    ThreadLocalStorage<T> &
    operator=(T &&t);
 
    void
    clear();
 
  private:
    std::map<std::thread::id, T> data;
 
    mutable std::shared_mutex insertion_mutex;
 
    std::shared_ptr<const T> exemplar;
  };
} // namespace Threads
#  ifndef DOXYGEN
namespace Threads
{
  // ----------------- inline and template functions --------------------------
 
 
  template <typename T>
  ThreadLocalStorage<T>::ThreadLocalStorage(const ThreadLocalStorage<T> &t)
    : exemplar(t.exemplar)
  {
    // Raise a reader lock while we are populating our own data in order to
    // avoid copying over an invalid state.
    std::shared_lock<decltype(insertion_mutex)> lock(t.insertion_mutex);
    data = t.data;
  }
 
 
 
  template <typename T>
  ThreadLocalStorage<T>::ThreadLocalStorage(ThreadLocalStorage<T> &&t) noexcept
    : exemplar(std::move(t.exemplar))
  {
    // We are nice and raise the writer lock before copying over internal
    // data structures from the argument.
    //
    // The point is a bit moot, though: Users of ThreadLocalStorage
    // typically obtain their thread's thread-local object through the
    // get() function. That function also acquires the lock, but
    // whether or not we do that here really doesn't make any
    // difference in terms of correctness: If another thread manages
    // to call get() just before we get here, then the result of that
    // get() function immediately becomes invalid; if it manages to
    // call get() at the same time as this function if there were no
    // locking here, it might access undefined state; and if it
    // manages to call get() just after we moved away the state --
    // well, then it just got lucky to escape the race condition, but
    // the race condition is still there.
    //
    // On the other hand, there is no harm in doing at least
    // conceptually the right thing, so ask for that lock:
    std::unique_lock<decltype(insertion_mutex)> lock(t.insertion_mutex);
    data = std::move(t.data);
  }
 
 
 
  template <typename T>
  inline ThreadLocalStorage<T>::ThreadLocalStorage(const T &t)
    : exemplar(std::make_shared<const T>(t))
  {}
 
 
 
  template <typename T>
  inline ThreadLocalStorage<T>::ThreadLocalStorage(T &&t)
    : exemplar(std::make_shared<T>(std::forward<T>(t)))
  {}
 
 
 
  template <typename T>
  inline ThreadLocalStorage<T> &
  ThreadLocalStorage<T>::operator=(const ThreadLocalStorage<T> &t)
  {
    // We need to raise the reader lock of the argument and our writer lock
    // while copying internal data structures.
    std::shared_lock<decltype(insertion_mutex)> reader_lock(t.insertion_mutex);
    std::unique_lock<decltype(insertion_mutex)> writer_lock(insertion_mutex);
 
    data     = t.data;
    exemplar = t.exemplar;
 
    return *this;
  }
 
 
 
  template <typename T>
  inline ThreadLocalStorage<T> &
  ThreadLocalStorage<T>::operator=(ThreadLocalStorage<T> &&t) noexcept
  {
    // We need to raise the writer lock of the argument (because we're
    // moving information *away* from that object) and the writer lock
    // of our object while copying internal data structures.
    //
    // That said, the same issue with acquiring the source lock as
    // with the move constructor above applies here as well.
    std::unique_lock<decltype(insertion_mutex)> reader_lock(t.insertion_mutex);
    std::unique_lock<decltype(insertion_mutex)> writer_lock(insertion_mutex);
 
    data     = std::move(t.data);
    exemplar = std::move(t.exemplar);
 
    return *this;
  }
 
 
#    ifndef DOXYGEN
  namespace internal
  {
    /*
     * We have to make sure not to call "data.emplace(id, *exemplar)" if
     * the corresponding element is not copy constructible. We use some
     * SFINAE magic to work around the fact that C++14 does not have
     * "if constexpr".
     */
    template <typename T>
    std::enable_if_t<
      std::is_copy_constructible_v<typename unpack_container<T>::type>,
      T &>
    construct_element(std::map<std::thread::id, T>   &data,
                      const std::thread::id          &id,
                      const std::shared_ptr<const T> &exemplar)
    {
      if (exemplar)
        {
          const auto it = data.emplace(id, *exemplar).first;
          return it->second;
        }
      return data[id];
    }
 
    template <typename T>
    std::enable_if_t<
      !std::is_copy_constructible_v<typename unpack_container<T>::type>,
      T &>
    construct_element(std::map<std::thread::id, T> &data,
                      const std::thread::id        &id,
                      const std::shared_ptr<const T> &)
    {
      return data[id];
    }
  } // namespace internal
#    endif
 
 
  template <typename T>
  inline T &
  ThreadLocalStorage<T>::get(bool &exists)
  {
    const std::thread::id my_id = std::this_thread::get_id();
 
    // Note that std::map<..>::emplace guarantees that no iterators or
    // references to stored objects are invalidated. We thus only have to
    // ensure that we do not perform a lookup while writing, and that we
    // do not write concurrently. This is precisely the "reader-writer
    // lock" paradigm supported by C++14 by means of the std::shared_lock
    // and the std::unique_lock.
 
    {
      // Take a shared ("reader") lock for lookup and record the fact
      // whether we could find an entry in the boolean exists.
      std::shared_lock<decltype(insertion_mutex)> lock(insertion_mutex);
 
      const auto it = data.find(my_id);
      if (it != data.end())
        {
          exists = true;
          return it->second;
        }
      else
        {
          exists = false;
        }
    }
 
    {
      // Take a unique ("writer") lock for manipulating the std::map. This
      // lock ensures that no other thread does a lookup at the same time.
      std::unique_lock<decltype(insertion_mutex)> lock(insertion_mutex);
 
      return internal::construct_element(data, my_id, exemplar);
    }
  }
 
 
  template <typename T>
  std::optional<T>
  ThreadLocalStorage<T>::get_for_thread(const std::thread::id &id) const
  {
    // Take a shared ("reader") lock for lookup:
    std::shared_lock<decltype(insertion_mutex)> lock(insertion_mutex);
 
    // Then see whether we can find the indicated object; if so, copy it,
    // otherwise return an empty std::optional.
    const auto it = data.find(id);
    if (it != data.end())
      return it->second;
    else
      return {};
  }
 
 
  template <typename T>
  inline T &
  ThreadLocalStorage<T>::get()
  {
    bool exists;
    return get(exists);
  }
 
 
  template <typename T>
  inline ThreadLocalStorage<T>::operator T &()
  {
    return get();
  }
 
 
  template <typename T>
  inline ThreadLocalStorage<T> &
  ThreadLocalStorage<T>::operator=(const T &t)
  {
    get() = t;
    return *this;
  }
 
 
  template <typename T>
  inline ThreadLocalStorage<T> &
  ThreadLocalStorage<T>::operator=(T &&t)
  {
    get() = std::forward<T>(t);
    return *this;
  }
 
 
  template <typename T>
  inline void
  ThreadLocalStorage<T>::clear()
  {
    std::unique_lock<decltype(insertion_mutex)> lock(insertion_mutex);
    data.clear();
  }
} // namespace Threads
 
#  endif // DOXYGEN
 
//---------------------------------------------------------------------------
DEAL_II_NAMESPACE_CLOSE
// end of #ifndef dealii_thread_local_storage_h
#endif
//---------------------------------------------------------------------------