Debian Codegraph @

include/deal.II/base/task_result.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2023 - 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_task_result_h
16 #define dealii_task_result_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/thread_management.h>
23
24 #include <atomic>
25 #include <mutex>
26 #include <optional>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 /**
31 * @addtogroup threads
32 * @{
33 */
34
35 namespace Threads
36 {
37 /**
38 * A class that represents the outcome of a Threads::Task. The class is used
39 * as a member variable or local variable when something is computed on a
40 * separate task in the background. For example, a class's constructor may
41 * want to set up some expensive data structures that are not typically
42 * used right away in the next line of the function that created the object,
43 * but will be useful later; in such a case, it may defer computation of that
44 * data to a separate task that will be scheduled whenever a CPU core is
45 * available, and the result of that deferred computation will become
46 * available through a variable of the current type.
47 *
48 * In some regard, class TaskResult is similar to class Lazy in that it
49 * defers construction of an object to a later point while already giving it
50 * a home. The difference is simply that TaskResult has the creation job
51 * already scheduled whereas Lazy defers creation to the first use. Lazy is
52 * therefore a better choice whenever the object referenced may or may not
53 * ever be used, say for some obscure functionality of a class that is rarely
54 * required. On the other hand, TaskResult is used for member variables that
55 * are definitely needed, but perhaps not right away.
56 *
57 * This class has an interface that is quite similar to the Threads::Task
58 * class itself, and object of which is provided to the constructor. The key
59 * difference is that the Task class describes the *task* that computes a
60 * result, whereas the current TaskResult class describes the *result* that is
61 * being computed by the task. The main practical differences between these
62 * perspectives are what happens when you want to copy an object: Copying a
63 * Task object results in two objects that are both referencing the same task,
64 * with the same returned object when the task has finished. On the other
65 * hand, copying a TaskResult object after the computing task has finished
66 * results in two copies of the returned object.
67 *
68 * This class can also be compared with
69 * [`std::future`](https://en.cppreference.com/w/cpp/thread/future). That
70 * class also represents the result of a pending operation, but it lacks the
71 * specifics of what kind of operation that is (in particular, it does not
72 * know whether a task, a thread, or a `std::packaged_task` will eventually
73 * produce the value). As a consequence, it can *wait* for
74 * the result to become available, but it lacks the knowledge to detect
75 * certain common programming mistakes such as those described in the
76 * documentation of the destructor of this class, or of this class's
77 * `operator=()`. Another significant difference is that
78 * one can only call `std::future::get()` once, whereas one
79 * can call Threads::Task::return_value() as many times as desired. It is,
80 * thus, comparable to the
81 * [`std::shared_future`](https://en.cppreference.com/w/cpp/thread/shared_future)
82 * class. However, `std::shared_future` can not be used for types that can not
83 * be copied -- a particular restriction for `std::unique_ptr`, for example.
84 */
85 template <typename T>
86 class TaskResult
87 {
88 public:
89 /**
90 * Default constructor. An object of this kind is not (presently)
91 * associated with a task, and so cannot be asked for that task's
92 * result.
93 */
94 TaskResult()
95 : result_is_available(false)
96 {}
97
98 /**
99 * A constructor that takes a Task object and initializes the
100 * current object to be the result of that task.
101 */
102 TaskResult(const Task<T> &task)
103 : result_is_available(false)
104 , task(task)
105 {
106 // It is conceivable that the task has already finished if we
107 // come to this point, but that is not important to us here:
108 // we will simply find out once someone calls get()
109 }
110
111 /**
112 * Copy constructor. Because the result of a currently still
113 * running task is a unique object, TaskResult objects cannot be
114 * copied.
115 */
116 TaskResult(const TaskResult<T> &) = delete;
117
118 /**
119 * Move constructor. Following this call, the newly created object
120 * represents the task's result, whereas the old object no longer
121 * represents anything and is left as if default-constructed.
122 */
123 TaskResult(TaskResult<T> &&other) noexcept DEAL_II_CXX20_REQUIRES(
124 std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>);
125
126 /**
127 * Destructor. If the current object was associated with a task,
128 * then the destructor will throw an error if that task is still
129 * running. This is because typically, the task will still be
130 * working on data that is already gone away, or will shortly go away, and
131 * that means that that task will likely encounter unpredictable
132 * outcomes. As an example, consider the following code:
133 * @code
134 * class Complicated {
135 * public:
136 * Complicated () {
137 * ...initialize members...;
138 * hash_value = Threads::new_task(
139 * [&]() { compute has value for the current object; });
140 * }
141 *
142 * ~Complicated() { ... }
143 *
144 * private:
145 * ...complicated data members...
146 * Threads::TaskResult<int> hash_value;
147 * ...more data members...
148 * };
149 * @endcode
150 * Here, the constructor `~Complicated()` destroys the object's member
151 * variables, and then calls the destructor of `hash_value`. If at the
152 * time we get to the latter destructor the background task to compute
153 * a hash value is still running, then this is strictly speaking not a
154 * problem for the `hash_value` variable (we could simply abandon the
155 * background task and its result), but it is indicative of a programming
156 * bug where that background task is now working on invalid memory.
157 * To catch these things, the destructor of this class will throw an error
158 * if it encounters a situation where the task it is associated with is
159 * still running.
160 *
161 * The correct solution is to wait in the surrounding class's destructor
162 * for the background task to finish before tearing down data structures:
163 * @code
164 * ~Complicated() {
165 * hash_value.join();
166 * ...tear down data structures...
167 * } // compilers calls hash_value's destructor here
168 * @endcode
169 *
170 * (One could have designed this class in such a way that the destructor
171 * waits for the task to complete. But this is error prone, because C++
172 * prescribes that destructors of member variables are called in reverse
173 * order in which they are declared, and so if this destructor is called
174 * by the compiler as part of a surrounding class's destructor, the
175 * destructors of all member variables have already run by the time
176 * we get to wait for the background task -- but the background task
177 * is likely still working on these data members, and that presents
178 * a probable bug. Instead, we force the destructor of the surrounding
179 * class to explicitly wait for the task to complete before reaching
180 * the end of the destructor at which the compiler inserts the calls
181 * to the destructors of the class's member variables.)
182 */
183 ~TaskResult();
184
185 /**
186 * Copy operator. Like the copy constructor, this function is deleted
187 * because TaskResult corresponds to the output of a specific task,
188 * not a copy of that tasks's outcome.
189 */
190 TaskResult &
191 operator=(const TaskResult &) = delete;
192
193 /**
194 * Move assignment operator. Following this call, the newly created object
195 * represents the task's result, whereas the old object no longer
196 * represents anything and is left as if default-constructed.
197 */
198 TaskResult &
199 operator=(TaskResult &&other) noexcept DEAL_II_CXX20_REQUIRES(
200 std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>);
201
202 /**
203 * Copy assignment operator from a Task object. By assigning the Task
204 * object to the current object, the current object is set to represent
205 * the result of that task.
206 *
207 * When calling this operator, the current object will no longer
208 * represent the result of a previous Task. If the previously associated
209 * task is still running, this function throws an exception. This is
210 * because assigning a new task to this object when the previous task
211 * is still running is likely a bug: In most cases, the new and old
212 * tasks are both operating on the state of another object; the fact
213 * that the old task is still running often indicates that it is working
214 * on data that has been changed underneath. To illustrate this, case,
215 * consider the following code snippet:
216 * @code
217 * class Complicated {
218 * public:
219 * Complicated () {
220 * ...initialize members...;
221 * hash_value = Threads::new_task(
222 * [&]() { compute has value for the current object; });
223 * }
224 *
225 * void frobnicate () {
226 * ...do something with members...;
227 * hash_value = Threads::new_task(
228 * [&]() { compute has value for the current object; });
229 * }
230 *
231 * private:
232 * ...complicated data members...
233 * Threads::TaskResult<int> hash_value;
234 * };
235 * @endcode
236 * Here, in `frobnicate()`, member variables are updated according to what
237 * the `frobnicate()` operation represents, and then the `hash_value`
238 * variable is updated as well, but in the background. The issue is that
239 * if the background task started in the constructor is still running,
240 * then that background task is working on data that is being changed
241 * beneath it, likely resulting in unpredictable outcomes. The correct
242 * approach would therefore be to write `frobnicate()` as follows:
243 * @code
244 * void frobnicate () {
245 * hash_value.join();
246 * ...do something with members...;
247 * hash_value = Threads::new_task(
248 * [&]() { compute has value for the current object; });
249 * }
250 * @endcode
251 * The call to join() ensures that the program waits for the previous task
252 * to finish before starting to modify the underlying data. (Calling
253 * `clear()` might seem like a useful alternative in that it simply abandons
254 * the first background task, but while that ensures that the first task's
255 * result are not put into the current object, it still means that that task
256 * is working on data that is changing as it is working, with obviously
257 * unpredictable results.)
258 *
259 * @note As mentioned above, it is a considered a bug to assign a task to
260 * a TaskResult object that already has a task running. That means that
261 * you will get in trouble if multiple threads (or multiple tasks running
262 * concurrently) call this operator at the same time: One of these
263 * threads will set a task, and the other threads will try the same but
264 * because the background task is likely still running will encounter
265 * an error. As a consequence, you cannot easily use this operator
266 * from multiple threads. Use try_emplace_task() in that case.
267 */
268 void
269 operator=(const Task<T> &t);
270
271 /**
272 * This function is similar to `operator=()` in that it associates a
273 * task with the current object if one has not been associated so far,
274 * but does not do so if a task is already assigned. For this to work,
275 * the object provided as argument to this function must be a "callable"
276 * (i.e., a object `creator` that can be called on a separate task via
277 * its `operator()`), rather than a Task object itself.
278 *
279 * As a consequence, code such as the following will work:
280 * @code
281 * class LazyInt
282 * {
283 * public:
284 * LazyInt () {} // no task assigned to task_result
285 *
286 * int get () {
287 * task_result.try_emplace_task( []() { return 42; } );
288 * return task_result.value();
289 * }
290 *
291 * private:
292 * TaskResult<int> task_result;
293 * }
294 * @endcode
295 * In this context, the `LazyInt::get()` function is thread-safe, i.e., it
296 * can be called more than once from multiple threads. One of these threads
297 * -- namely, the first one to get into `try_emplace_task()` -- will create
298 * a task that calls the lambda function that returns `42` whereas all of
299 * the others will simply proceed to the call to `value()` that waits for
300 * the task to finish.
301 *
302 * On the other hand, implementing the `get()` function as
303 * @code
304 * int get () {
305 * task_result = Threads::new_task( []() { return 42; } );
306 * return task_result.value();
307 * }
308 * @endcode
309 * would have led to the errors mentioned above because `operator=` called
310 * from separate threads would have emplaced a task while another task
311 * is (possibly) still running.
312 *
313 * @note There is nothing that prevents you from concurrently calling
314 * this function with *different* callables as arguments, i.e., with
315 * functions that create non-identical objects. That is obviously
316 * not the intent here since you can't control which callable will
317 * eventually be turned into a task.
318 */
319 template <typename Callable>
320 void
321 try_emplace_task(const Callable &creator) const
322 DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>));
323
324 /**
325 * Instead of letting a task compute the object stored by this
326 * instance of Lazy, just copy the object passed as an argument
327 * and use it instead.
328 *
329 * As for several other member functions, this function can only be called
330 * if there is not currently a running task whose result is supposed to
331 * be used.
332 */
333 void
334 emplace_object(const T &t)
335 DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
336 std::is_copy_assignable_v<T>));
337
338 /**
339 * Instead of letting a task compute the object stored by this
340 * instance of Lazy, just move the object passed as an argument
341 * and use it instead.
342 *
343 * As for several other member functions, this function can only be called
344 * if there is not currently a running task whose result is supposed to
345 * be used.
346 */
347 void
348 emplace_object(T &&t)
349 DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
350 std::is_copy_assignable_v<T>));
351
352 /**
353 * Reset the current object to a state as if it had been
354 * default-constructed. For the same reasons as outlined
355 * in the documentation of the destructor and of the
356 * assignment operator, this function considers it an
357 * error (and throws an exception) if there is still a
358 * currently running task associated with the object.
359 * Because you cannot know when a task associated with an
360 * object finishes, the practical realization of there not being
361 * a currently still running task is that you can only call this
362 * function on an object that has an associated task *after* you
363 * have either called join() or asked for the return value by
364 * having called value() (which internally calls join()).
365 */
366 void
367 clear();
368
369 /**
370 * If this object is associated with a task, wait for it to finish. If
371 * it isn't associated with a task, just return.
372 */
373 void
374 join() const;
375
376 /**
377 * Return a reference to the object computed by the task. This
378 * is always a `const` reference to reflect the semantics that this
379 * object represents what the Threads::Task computed (which is what it
380 * is, and cannot be changed later on).
381 */
382 const T &
383 value() const;
384
385 /**
386 * Return whether the object has an associated task result object or not.
387 * Only objects that are default-initialized, or for which clear() has
388 * been called, or that have been moved from, will return `true` in
389 * this function.
390 */
391 bool
392 empty() const;
393
394 private:
395 /**
396 * An atomic flag that allows us to test whether the task has finished
397 * and the result is available.
398 */
399 mutable std::atomic<bool> result_is_available;
400
401 /**
402 * An object that references the task that computes the result TaskResult
403 * stores. Once the task has finished, and the result has been moved out
404 * of the `task` object and into `task_result`, the `task` object is
405 * reset -- that is, we destroy all traces of references to the Thread::Task
406 * that computed the result.
407 */
408 mutable std::optional<Task<T>> task;
409
410 /**
411 * The object that results from running the background task.
412 */
413 mutable std::optional<T> task_result;
414
415 /**
416 * A lock object that guards access to all of the `mutable` objects above.
417 */
418 mutable std::mutex mutex;
419 };
420
421
422 // ------------------------------- inline functions --------------------------
423
424 #ifndef DOXYGEN
425
426 template <typename T>
427 inline TaskResult<T>::TaskResult(TaskResult<T> &&other) noexcept
428 DEAL_II_CXX20_REQUIRES(
429 std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>)
430 {
431 // First lock the other object, then move the members of the other
432 // object and reset it. Note that we do not have to wait for
433 // the other object's task to finish (nor should we).
434 std::lock_guard<std::mutex> lock(other.mutex);
435
436 result_is_available = other.result_is_available.load();
437 other.result_is_available = false;
438
439 task = std::move(other.task);
440 other.task.reset();
441
442 task_result = std::move(other.task_result);
443 other.task_result.reset();
444 }
445
446
447
448 template <typename T>
449 inline TaskResult<T>::~TaskResult()
450 {
451 // Ensure that there is no currently running task. As
452 // documented, we consider this an error. Since clear()
453 // also checks for this error, we can just defer to that function:
454 clear();
455 }
456
457
458
459 template <typename T>
460 inline void
461 TaskResult<T>::operator=(const Task<T> &t)
462 {
463 // First ensure that there is no currently running task. As
464 // documented, we consider this an error. Since clear()
465 // also checks for this error, we can just defer to that function:
466 clear();
467
468 // Having established that there is no previous task still running,
469 // set the current task as the one we're waiting for:
470 {
471 std::lock_guard<std::mutex> lock(mutex);
472 task = t;
473 }
474 }
475
476
477 template <typename T>
478 inline TaskResult<T> &
479 TaskResult<T>::operator=(TaskResult<T> &&other) noexcept
480 DEAL_II_CXX20_REQUIRES(
481 std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>)
482 {
483 // First clear the current object before we put new content into it:
484 clear();
485
486 // Then lock the other object and move the members of the other
487 // object, and finally reset it. Note that we do not have to wait for
488 // the other object's task to finish (nor should we): We may simply
489 // inherit the other object's task.
490 std::lock_guard<std::mutex> lock(other.mutex);
491
492 result_is_available = other.result_is_available.load();
493 other.result_is_available = false;
494
495 task = std::move(other.task);
496 other.task.reset();
497
498 task_result = std::move(other.task_result);
499 other.task_result.reset();
500
501 return *this;
502 }
503
504
505
506 template <typename T>
507 template <typename Callable>
508 void
509 TaskResult<T>::try_emplace_task(const Callable &creator) const
510 DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>))
511 {
512 // If the result is already available, simply return.
513 if (result_is_available)
514 return;
515
516 // If the result was not available above, we need to go under a lock
517 // to check that perhaps it has appeared in the meantime. We again use
518 // the double-checking pattern:
519 {
520 std::lock_guard<std::mutex> lock(mutex);
521 if (result_is_available)
522 return;
523 else
524 // If there is no result, but there is a task, some other thread has
525 // emplaced it in the meantime and we can simply return
526 if (task.has_value())
527 return;
528 else
529 // If there is no task object, emplace one:
530 task = Threads::new_task(creator);
531 }
532 }
533
534
535
536 template <typename T>
537 inline void
538 TaskResult<T>::emplace_object(const T &t)
539 DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
540 std::is_copy_assignable_v<T>))
541 {
542 clear();
543 task_result = t;
544 result_is_available = true;
545 }
546
547
548 template <typename T>
549 inline void
550 TaskResult<T>::emplace_object(T &&t)
551 DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
552 std::is_copy_assignable_v<T>))
553 {
554 clear();
555 task_result = std::move(t);
556 result_is_available = true;
557 }
558
559
560 template <typename T>
561 inline void
562 TaskResult<T>::clear()
563 {
564 std::lock_guard<std::mutex> lock(mutex);
565
566 if (result_is_available)
567 {
568 // First make clear that the result is no longer available, then
569 // reset the object:
570 result_is_available = false;
571 task_result.reset();
572 }
573 else
574 Assert(task.has_value() == false,
575 ExcMessage("You cannot destroy a TaskResult object "
576 "while it is still waiting for its associated task "
577 "to finish. See the documentation of this class' "
578 "destructor for more information."));
579 }
580
581
582
583 template <typename T>
584 inline void
585 TaskResult<T>::join() const
586 {
587 Assert(empty() == false,
588 ExcMessage("You can't join a TaskResult object that has not "
589 "been associated with a task."));
590
591 // If we have waited before, then return immediately:
592 if (result_is_available)
593 return;
594 else
595 // If we have not waited, wait now. We need to use the double-checking
596 // pattern to ensure that if two threads get to this place at the same
597 // time, one returns right away while the other does the work. Note
598 // that this happens under the lock, so only one thread gets to be in
599 // this code block at the same time:
600 {
601 std::lock_guard<std::mutex> lock(mutex);
602 if (result_is_available)
603 return;
604 else
605 {
606 // The object is not empty and it has not received its result yet.
607 // So it must have a task object:
608 Assert(task.has_value(), ExcInternalError());
609
610 task.value().join();
611 task_result = std::move(task.value().return_value());
612 task.reset();
613
614 result_is_available = true;
615 }
616 }
617 }
618
619
620
621 template <typename T>
622 inline bool
623 TaskResult<T>::empty() const
624 {
625 // If we have waited for a task to complete, then the object is not empty:
626 if (result_is_available)
627 return false;
628 // Otherwise, if result_is_available has not been set, but we have a task
629 // associated (i.e., the task is still running, or at least we haven't
630 // waited for it to complete), then the object is also not empty:
631 else if (task.has_value())
632 return false;
633 else
634 // If when we asked above we had not joined a task, and if there was
635 // no task currently associated with the object, then one of two cases
636 // could have happened: either, there never was a task, and the object
637 // is consequently empty. Or there was a task and somewhere between the
638 // checks above and now, join() has flipped the state to
639 // result_is_available==true and task.has_value()==false. We can
640 // check that, but only under a lock.
641 {
642 std::lock_guard<std::mutex> lock(mutex);
643 if (result_is_available)
644 return false;
645 else
646 // We know from getting into the above 'else that no task was
647 // associated with this object at the time. This cannot have
648 // changed since then in a way that is thread-safe (i.e., by
649 // way of other 'const' functions), so if the result is still
650 // not available, then the object must necessarily be empty:
651 return true;
652 }
653 }
654
655
656
657 template <typename T>
658 inline const T &
659 TaskResult<T>::value() const
660 {
661 Assert(empty() == false,
662 ExcMessage(
663 "You can't ask for the result of a TaskResult object that "
664 "has not been associated with a task."));
665
666 if (!result_is_available)
667 join();
668 return task_result.value();
669 }
670
671 #endif
672
673 } // namespace Threads
674
675
676 /**
677 * @}
678 */
679
680
681
682 DEAL_II_NAMESPACE_CLOSE
683 #endif