Debian Codegraph @

include/deal.II/base/thread_local_storage.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2011 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_thread_local_storage_h
16 # define dealii_thread_local_storage_h
17
18
19 # include <deal.II/base/config.h>
20
21 # include <deal.II/base/exceptions.h>
22
23 # include <list>
24 # include <map>
25 # include <memory>
26 # include <mutex>
27 # include <optional>
28 # include <shared_mutex>
29 # include <thread>
30 # include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 /**
35 * @addtogroup threads
36 * @{
37 */
38
39 # ifndef DOXYGEN
40 class LogStream;
41 # endif
42
43 namespace Threads
44 {
45 # ifndef DOXYGEN
46 namespace internal
47 {
48 /*
49 * Workaround: The standard unfortunately has an unfortunate design
50 * "flaw" in the std::is_copy_constructible type trait
51 * when it comes to STL containers and containing non-copyable objects
52 * T. The type trait is true even though any attempted invocation leads
53 * to a compilation error. Work around this issue by unpacking some
54 * commonly used containers:
55 */
56 template <typename T>
57 struct unpack_container
58 {
59 using type = T;
60 };
61
62 template <typename T, typename A>
63 struct unpack_container<std::vector<T, A>>
64 {
65 using type = T;
66 };
67
68 template <typename T, typename A>
69 struct unpack_container<std::list<T, A>>
70 {
71 using type = T;
72 };
73 } // namespace internal
74 # endif
75
76 /**
77 * @brief A class that provides a separate storage location on each thread
78 * that accesses the object.
79 *
80 * This class offers ways so that every thread that accesses it has its own
81 * copy of an object of type T. In essence, accessing this object can never
82 * result in race conditions in multithreaded programs since no other thread
83 * than the current one can ever access it.
84 *
85 * <h3>Construction and destruction</h3>
86 *
87 * Objects of this class can either be default constructed or by providing
88 * an "exemplar", i.e. an object of type T so that every time we need to
89 * create a T on a thread that doesn't already have such an object, it is
90 * copied from the exemplar.
91 *
92 * Upon destruction of objects of this class, all T objects that correspond
93 * to threads that have accessed this object are destroyed. Note that this
94 * may be before the time when a thread is terminated.
95 *
96 * <h3>Access</h3>
97 *
98 * The T object stored by this object can be accessed using the get()
99 * function. It provides a reference to a unique object when accessed from
100 * different threads. Objects of type T are created lazily, i.e. they are
101 * only created whenever a thread actually calls get().
102 */
103 template <typename T>
104 class ThreadLocalStorage
105 {
106 static_assert(
107 std::is_copy_constructible_v<
108 typename internal::unpack_container<T>::type> ||
109 std::is_default_constructible_v<T>,
110 "The stored type must be either copyable, or default constructible");
111
112 public:
113 /**
114 * Default constructor. Initialize each thread local object using its
115 * default constructor.
116 */
117 ThreadLocalStorage() = default;
118
119 /**
120 * Copy constructor.
121 */
122 ThreadLocalStorage(const ThreadLocalStorage &);
123
124 /**
125 * Move constructor. The constructor moves all internal data structures
126 * from the argument.
127 */
128 ThreadLocalStorage(ThreadLocalStorage &&t) noexcept;
129
130 /**
131 * A kind of copy constructor. Initializes an internal exemplar by the
132 * given object. The exemplar is in turn used to initialize each thread
133 * local object instead of invoking the default constructor.
134 */
135 explicit ThreadLocalStorage(const T &t);
136
137 /**
138 * A kind of move constructor. Moves the given object into an internal
139 * exemplar. The exemplar is in turn used to initialize each thread
140 * local object instead of invoking the default constructor.
141 */
142 explicit ThreadLocalStorage(T &&t);
143
144 /**
145 * Copy assignment operator.
146 */
147 ThreadLocalStorage &
148 operator=(const ThreadLocalStorage &t);
149
150 /**
151 * Move assignment operator.
152 */
153 ThreadLocalStorage &
154 operator=(ThreadLocalStorage &&t) noexcept;
155
156 /**
157 * Return a reference to the data stored by this object for the current
158 * thread this function is called on.
159 *
160 * Note that there is no member function get() that is const and returns a
161 * const reference as one would expect. The reason is that if such a
162 * member function were called on a thread for which no thread-local
163 * object has been created yet, then one has to create such an object
164 * first which would certainly be a non-constant operation. If you need to
165 * call the get() function for a member variable of a class from a const
166 * member function, then you need to declare the member variable
167 * <code>mutable</code> to allow such access.
168 */
169 T &
170 get();
171
172 /**
173 * Same as above, except that @p exists is set to true if an element was
174 * already present for the current thread; false otherwise.
175 */
176 T &
177 get(bool &exists);
178
179 /**
180 * If the thread with given `id` has an object currently stored, then return
181 * it by value via the `std::optional` object. If the indicated thread does
182 * not have an object stored, return an empty `std::optional`.
183 *
184 * Note that in the successful case, this function returns a *copy* of
185 * the object, unlike get() which returns a reference to it. This is
186 * because when you call get(), you are calling it from the current
187 * thread (i.e., the thread that "owns" the object), and so all accesses
188 * are by definition not concurrent. On the other hand, if you are asking
189 * about the object owned by a different thread, that other thread might
190 * concurrently be accessing it and that might cause race conditions.
191 * To avoid these, the function here returns a copy.
192 */
193 std::optional<T>
194 get_for_thread(const std::thread::id &id) const;
195
196 /**
197 * Conversion operator that simply converts the thread-local object to the
198 * data type that it stores. This function is equivalent to calling the
199 * get() member function; it's purpose is to make the TLS object look more
200 * like the object it is storing.
201 */
202 operator T &();
203
204 /**
205 * Copy the given argument into the storage space used to represent the
206 * current thread. Calling this function as <code>tls_data = object</code>
207 * is equivalent to calling <code>tls_data.get() = object</code>. The
208 * intent of this operator is to make the ThreadLocalStorage object look
209 * more like the object it represents on the current thread.
210 *
211 * @param t The object to be copied into the storage space used for the
212 * current thread.
213 *
214 * @return The current object, after the changes have been made
215 */
216 ThreadLocalStorage<T> &
217 operator=(const T &t);
218
219 /**
220 * Move the given argument into the storage space used to represent the
221 * current thread. Calling this function as <code>tls_data =
222 * object</code> is equivalent to calling <code>tls_data.get() =
223 * object</code>. The intent of this operator is to make the
224 * ThreadLocalStorage object look more like the object it represents on
225 * the current thread. Move assignment operator.
226 *
227 * @param t The object to be copied into the storage space used for the
228 * current thread.
229 *
230 * @return The current object, after the changes have been made
231 */
232 ThreadLocalStorage<T> &
233 operator=(T &&t);
234
235 /**
236 * Remove the thread-local objects stored for all threads that have
237 * created one with this object (i.e., that have called get() at least
238 * once on this thread. This includes the current thread. If you call
239 * get() subsequently on this or any other thread, new objects will again
240 * be created.
241 *
242 * If deal.II has been configured to not use multithreading, then this
243 * function does not do anything at all. Note that this of course has
244 * different semantics as in the multithreading context the objects are
245 * deleted and created again (possible by copying from a sample object, if
246 * the appropriate constructor of this class was called), whereas in the
247 * multithreaded context the object is simply not touched at all. At the
248 * same time, the purpose of this function is to release memory other
249 * threads may have allocated for their own thread local objects after
250 * which every use of this object will require some kind of
251 * initialization. This is necessary both in the multithreaded or
252 * non-multithreaded case.
253 */
254 void
255 clear();
256
257 private:
258 /**
259 * The data element we store.
260 */
261 std::map<std::thread::id, T> data;
262
263 /**
264 * A mutex to guard insertion into the data object.
265 *
266 * We use a std::shared_timed_mutex (or std::shared_mutex if available)
267 * here to be able to use std::unique_lock and std::shared_lock for a
268 * readers-writer lock
269 * (https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock).
270 */
271 mutable std::shared_mutex insertion_mutex;
272
273 /**
274 * An exemplar for creating a new (thread specific) copy.
275 */
276 std::shared_ptr<const T> exemplar;
277 };
278 } // namespace Threads
279 /**
280 * @}
281 */
282
283 # ifndef DOXYGEN
284 namespace Threads
285 {
286 // ----------------- inline and template functions --------------------------
287
288
289 template <typename T>
290 ThreadLocalStorage<T>::ThreadLocalStorage(const ThreadLocalStorage<T> &t)
291 : exemplar(t.exemplar)
292 {
293 // Raise a reader lock while we are populating our own data in order to
294 // avoid copying over an invalid state.
295 std::shared_lock<decltype(insertion_mutex)> lock(t.insertion_mutex);
296 data = t.data;
297 }
298
299
300
301 template <typename T>
302 ThreadLocalStorage<T>::ThreadLocalStorage(ThreadLocalStorage<T> &&t) noexcept
303 : exemplar(std::move(t.exemplar))
304 {
305 // We are nice and raise the writer lock before copying over internal
306 // data structures from the argument.
307 //
308 // The point is a bit moot, though: Users of ThreadLocalStorage
309 // typically obtain their thread's thread-local object through the
310 // get() function. That function also acquires the lock, but
311 // whether or not we do that here really doesn't make any
312 // difference in terms of correctness: If another thread manages
313 // to call get() just before we get here, then the result of that
314 // get() function immediately becomes invalid; if it manages to
315 // call get() at the same time as this function if there were no
316 // locking here, it might access undefined state; and if it
317 // manages to call get() just after we moved away the state --
318 // well, then it just got lucky to escape the race condition, but
319 // the race condition is still there.
320 //
321 // On the other hand, there is no harm in doing at least
322 // conceptually the right thing, so ask for that lock:
323 std::unique_lock<decltype(insertion_mutex)> lock(t.insertion_mutex);
324 data = std::move(t.data);
325 }
326
327
328
329 template <typename T>
330 inline ThreadLocalStorage<T>::ThreadLocalStorage(const T &t)
331 : exemplar(std::make_shared<const T>(t))
332 {}
333
334
335
336 template <typename T>
337 inline ThreadLocalStorage<T>::ThreadLocalStorage(T &&t)
338 : exemplar(std::make_shared<T>(std::forward<T>(t)))
339 {}
340
341
342
343 template <typename T>
344 inline ThreadLocalStorage<T> &
345 ThreadLocalStorage<T>::operator=(const ThreadLocalStorage<T> &t)
346 {
347 // We need to raise the reader lock of the argument and our writer lock
348 // while copying internal data structures.
349 std::shared_lock<decltype(insertion_mutex)> reader_lock(t.insertion_mutex);
350 std::unique_lock<decltype(insertion_mutex)> writer_lock(insertion_mutex);
351
352 data = t.data;
353 exemplar = t.exemplar;
354
355 return *this;
356 }
357
358
359
360 template <typename T>
361 inline ThreadLocalStorage<T> &
362 ThreadLocalStorage<T>::operator=(ThreadLocalStorage<T> &&t) noexcept
363 {
364 // We need to raise the writer lock of the argument (because we're
365 // moving information *away* from that object) and the writer lock
366 // of our object while copying internal data structures.
367 //
368 // That said, the same issue with acquiring the source lock as
369 // with the move constructor above applies here as well.
370 std::unique_lock<decltype(insertion_mutex)> reader_lock(t.insertion_mutex);
371 std::unique_lock<decltype(insertion_mutex)> writer_lock(insertion_mutex);
372
373 data = std::move(t.data);
374 exemplar = std::move(t.exemplar);
375
376 return *this;
377 }
378
379
380 # ifndef DOXYGEN
381 namespace internal
382 {
383 /*
384 * We have to make sure not to call "data.emplace(id, *exemplar)" if
385 * the corresponding element is not copy constructible. We use some
386 * SFINAE magic to work around the fact that C++14 does not have
387 * "if constexpr".
388 */
389 template <typename T>
390 std::enable_if_t<
391 std::is_copy_constructible_v<typename unpack_container<T>::type>,
392 T &>
393 construct_element(std::map<std::thread::id, T> &data,
394 const std::thread::id &id,
395 const std::shared_ptr<const T> &exemplar)
396 {
397 if (exemplar)
398 {
399 const auto it = data.emplace(id, *exemplar).first;
400 return it->second;
401 }
402 return data[id];
403 }
404
405 template <typename T>
406 std::enable_if_t<
407 !std::is_copy_constructible_v<typename unpack_container<T>::type>,
408 T &>
409 construct_element(std::map<std::thread::id, T> &data,
410 const std::thread::id &id,
411 const std::shared_ptr<const T> &)
412 {
413 return data[id];
414 }
415 } // namespace internal
416 # endif
417
418
419 template <typename T>
420 inline T &
421 ThreadLocalStorage<T>::get(bool &exists)
422 {
423 const std::thread::id my_id = std::this_thread::get_id();
424
425 // Note that std::map<..>::emplace guarantees that no iterators or
426 // references to stored objects are invalidated. We thus only have to
427 // ensure that we do not perform a lookup while writing, and that we
428 // do not write concurrently. This is precisely the "reader-writer
429 // lock" paradigm supported by C++14 by means of the std::shared_lock
430 // and the std::unique_lock.
431
432 {
433 // Take a shared ("reader") lock for lookup and record the fact
434 // whether we could find an entry in the boolean exists.
435 std::shared_lock<decltype(insertion_mutex)> lock(insertion_mutex);
436
437 const auto it = data.find(my_id);
438 if (it != data.end())
439 {
440 exists = true;
441 return it->second;
442 }
443 else
444 {
445 exists = false;
446 }
447 }
448
449 {
450 // Take a unique ("writer") lock for manipulating the std::map. This
451 // lock ensures that no other thread does a lookup at the same time.
452 std::unique_lock<decltype(insertion_mutex)> lock(insertion_mutex);
453
454 return internal::construct_element(data, my_id, exemplar);
455 }
456 }
457
458
459 template <typename T>
460 std::optional<T>
461 ThreadLocalStorage<T>::get_for_thread(const std::thread::id &id) const
462 {
463 // Take a shared ("reader") lock for lookup:
464 std::shared_lock<decltype(insertion_mutex)> lock(insertion_mutex);
465
466 // Then see whether we can find the indicated object; if so, copy it,
467 // otherwise return an empty std::optional.
468 const auto it = data.find(id);
469 if (it != data.end())
470 return it->second;
471 else
472 return {};
473 }
474
475
476 template <typename T>
477 inline T &
478 ThreadLocalStorage<T>::get()
479 {
480 bool exists;
481 return get(exists);
482 }
483
484
485 template <typename T>
486 inline ThreadLocalStorage<T>::operator T &()
487 {
488 return get();
489 }
490
491
492 template <typename T>
493 inline ThreadLocalStorage<T> &
494 ThreadLocalStorage<T>::operator=(const T &t)
495 {
496 get() = t;
497 return *this;
498 }
499
500
501 template <typename T>
502 inline ThreadLocalStorage<T> &
503 ThreadLocalStorage<T>::operator=(T &&t)
504 {
505 get() = std::forward<T>(t);
506 return *this;
507 }
508
509
510 template <typename T>
511 inline void
512 ThreadLocalStorage<T>::clear()
513 {
514 std::unique_lock<decltype(insertion_mutex)> lock(insertion_mutex);
515 data.clear();
516 }
517 } // namespace Threads
518
519 # endif // DOXYGEN
520
521 //---------------------------------------------------------------------------
522 DEAL_II_NAMESPACE_CLOSE
523 // end of #ifndef dealii_thread_local_storage_h
524 #endif
525 //---------------------------------------------------------------------------