Reference documentation for deal.II version GIT relicensing-487-ge9eb5ab491 2024-04-25 07:20:02+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Loading...
Searching...
No Matches
Public Member Functions | Private Attributes | List of all members
Threads::ThreadLocalStorage< T > Class Template Reference

A class that provides a separate storage location on each thread that accesses the object. More...

#include <deal.II/base/thread_local_storage.h>

Inheritance diagram for Threads::ThreadLocalStorage< T >:
Inheritance graph
[legend]

Public Member Functions

 ThreadLocalStorage ()=default
 
 ThreadLocalStorage (const ThreadLocalStorage &)
 
 ThreadLocalStorage (ThreadLocalStorage &&t) noexcept
 
 ThreadLocalStorage (const T &t)
 
 ThreadLocalStorage (T &&t)
 
ThreadLocalStorageoperator= (const ThreadLocalStorage &t)
 
ThreadLocalStorageoperator= (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 Attributes

std::map< std::thread::id, T > data
 
std::shared_mutex insertion_mutex
 
std::shared_ptr< const T > exemplar
 

Detailed Description

template<typename T>
class Threads::ThreadLocalStorage< T >

A class that provides a separate storage location on each thread that accesses the object.

This class offers ways so that every thread that accesses it has its own copy of an object of type T. In essence, accessing this object can never result in race conditions in multithreaded programs since no other thread than the current one can ever access it.

Construction and destruction

Objects of this class can either be default constructed or by providing an "exemplar", i.e. an object of type T so that every time we need to create a T on a thread that doesn't already have such an object, it is copied from the exemplar.

Upon destruction of objects of this class, all T objects that correspond to threads that have accessed this object are destroyed. Note that this may be before the time when a thread is terminated.

Access

The T object stored by this object can be accessed using the get() function. It provides a reference to a unique object when accessed from different threads. Objects of type T are created lazily, i.e. they are only created whenever a thread actually calls get().

Definition at line 104 of file thread_local_storage.h.

Constructor & Destructor Documentation

◆ ThreadLocalStorage() [1/5]

template<typename T >
Threads::ThreadLocalStorage< T >::ThreadLocalStorage ( )
default

Default constructor. Initialize each thread local object using its default constructor.

◆ ThreadLocalStorage() [2/5]

template<typename T >
Threads::ThreadLocalStorage< T >::ThreadLocalStorage ( const ThreadLocalStorage< T > &  )

Copy constructor.

◆ ThreadLocalStorage() [3/5]

template<typename T >
Threads::ThreadLocalStorage< T >::ThreadLocalStorage ( ThreadLocalStorage< T > &&  t)
noexcept

Move constructor. The constructor moves all internal data structures from the argument.

◆ ThreadLocalStorage() [4/5]

template<typename T >
Threads::ThreadLocalStorage< T >::ThreadLocalStorage ( const T &  t)
explicit

A kind of copy constructor. Initializes an internal exemplar by the given object. The exemplar is in turn used to initialize each thread local object instead of invoking the default constructor.

◆ ThreadLocalStorage() [5/5]

template<typename T >
Threads::ThreadLocalStorage< T >::ThreadLocalStorage ( T &&  t)
explicit

A kind of move constructor. Moves the given object into an internal exemplar. The exemplar is in turn used to initialize each thread local object instead of invoking the default constructor.

Member Function Documentation

◆ operator=() [1/4]

template<typename T >
ThreadLocalStorage & Threads::ThreadLocalStorage< T >::operator= ( const ThreadLocalStorage< T > &  t)

Copy assignment operator.

◆ operator=() [2/4]

template<typename T >
ThreadLocalStorage & Threads::ThreadLocalStorage< T >::operator= ( ThreadLocalStorage< T > &&  t)
noexcept

Move assignment operator.

◆ get() [1/2]

template<typename T >
T & Threads::ThreadLocalStorage< T >::get ( )

Return a reference to the data stored by this object for the current thread this function is called on.

Note that there is no member function get() that is const and returns a const reference as one would expect. The reason is that if such a member function were called on a thread for which no thread-local object has been created yet, then one has to create such an object first which would certainly be a non-constant operation. If you need to call the get() function for a member variable of a class from a const member function, then you need to declare the member variable mutable to allow such access.

◆ get() [2/2]

template<typename T >
T & Threads::ThreadLocalStorage< T >::get ( bool exists)

Same as above, except that exists is set to true if an element was already present for the current thread; false otherwise.

◆ get_for_thread()

template<typename T >
std::optional< T > Threads::ThreadLocalStorage< T >::get_for_thread ( const std::thread::id &  id) const

If the thread with given id has an object currently stored, then return it by value via the std::optional object. If the indicated thread does not have an object stored, return an empty std::optional.

Note that in the successful case, this function returns a copy of the object, unlike get() which returns a reference to it. This is because when you call get(), you are calling it from the current thread (i.e., the thread that "owns" the object), and so all accesses are by definition not concurrent. On the other hand, if you are asking about the object owned by a different thread, that other thread might concurrently be accessing it and that might cause race conditions. To avoid these, the function here returns a copy.

◆ operator T&()

template<typename T >
Threads::ThreadLocalStorage< T >::operator T& ( )

Conversion operator that simply converts the thread-local object to the data type that it stores. This function is equivalent to calling the get() member function; it's purpose is to make the TLS object look more like the object it is storing.

◆ operator=() [3/4]

template<typename T >
ThreadLocalStorage< T > & Threads::ThreadLocalStorage< T >::operator= ( const T &  t)

Copy the given argument into the storage space used to represent the current thread. Calling this function as tls_data = object is equivalent to calling tls_data.get() = object. The intent of this operator is to make the ThreadLocalStorage object look more like the object it represents on the current thread.

Parameters
tThe object to be copied into the storage space used for the current thread.
Returns
The current object, after the changes have been made

◆ operator=() [4/4]

template<typename T >
ThreadLocalStorage< T > & Threads::ThreadLocalStorage< T >::operator= ( T &&  t)

Move the given argument into the storage space used to represent the current thread. Calling this function as tls_data = object is equivalent to calling tls_data.get() = object. The intent of this operator is to make the ThreadLocalStorage object look more like the object it represents on the current thread. Move assignment operator.

Parameters
tThe object to be copied into the storage space used for the current thread.
Returns
The current object, after the changes have been made

◆ clear()

template<typename T >
void Threads::ThreadLocalStorage< T >::clear ( )

Remove the thread-local objects stored for all threads that have created one with this object (i.e., that have called get() at least once on this thread. This includes the current thread. If you call get() subsequently on this or any other thread, new objects will again be created.

If deal.II has been configured to not use multithreading, then this function does not do anything at all. Note that this of course has different semantics as in the multithreading context the objects are deleted and created again (possible by copying from a sample object, if the appropriate constructor of this class was called), whereas in the multithreaded context the object is simply not touched at all. At the same time, the purpose of this function is to release memory other threads may have allocated for their own thread local objects after which every use of this object will require some kind of initialization. This is necessary both in the multithreaded or non-multithreaded case.

Member Data Documentation

◆ data

template<typename T >
std::map<std::thread::id, T> Threads::ThreadLocalStorage< T >::data
private

The data element we store.

Definition at line 261 of file thread_local_storage.h.

◆ insertion_mutex

template<typename T >
std::shared_mutex Threads::ThreadLocalStorage< T >::insertion_mutex
mutableprivate

A mutex to guard insertion into the data object.

We use a std::shared_timed_mutex (or std::shared_mutex if available) here to be able to use std::unique_lock and std::shared_lock for a readers-writer lock (https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock).

Definition at line 271 of file thread_local_storage.h.

◆ exemplar

template<typename T >
std::shared_ptr<const T> Threads::ThreadLocalStorage< T >::exemplar
private

An exemplar for creating a new (thread specific) copy.

Definition at line 276 of file thread_local_storage.h.


The documentation for this class was generated from the following file: