From 31508309e295da3b74508d81346672b99cc3dd6e Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 2 Jul 2024 17:45:25 -0600 Subject: [PATCH] Augment documentation. --- include/deal.II/base/task_result.h | 17 +++++++++++++---- include/deal.II/base/thread_management.h | 21 +++++++++++---------- 2 files changed, 24 insertions(+), 14 deletions(-) diff --git a/include/deal.II/base/task_result.h b/include/deal.II/base/task_result.h index b9e62c9c13..77c588a3e2 100644 --- a/include/deal.II/base/task_result.h +++ b/include/deal.II/base/task_result.h @@ -66,13 +66,22 @@ namespace Threads * hand, copying a TaskResult object after the computing task has finished * results in two copies of the returned object. * - * This class can also be compared with `std::future`. That class also - * represents the result of a pending operation, but it lacks the specifics - * of what kind of operation that is. As a consequence, it can *wait* for + * This class can also be compared with + * [`std::future`](https://en.cppreference.com/w/cpp/thread/future). That + * class also represents the result of a pending operation, but it lacks the + * specifics of what kind of operation that is (in particular, it does not + * know whether a task, a thread, or a `std::packaged_task` will eventually + * produce the value). As a consequence, it can *wait* for * the result to become available, but it lacks the knowledge to detect * certain common programming mistakes such as those described in the * documentation of the destructor of this class, or of this class's - * `operator=()`. + * `operator=()`. Another significant difference is that + * one can only call `std::future::get()` once, whereas one + * can call Threads::Task::return_value() as many times as desired. It is, + * thus, comparable to the + * [`std::shared_future`](https://en.cppreference.com/w/cpp/thread/shared_future) + * class. However, `std::shared_future` can not be used for types that can not + * be copied -- a particular restriction for `std::unique_ptr`, for example. */ template class TaskResult diff --git a/include/deal.II/base/thread_management.h b/include/deal.II/base/thread_management.h index db0a9b7a60..b69d4611a3 100644 --- a/include/deal.II/base/thread_management.h +++ b/include/deal.II/base/thread_management.h @@ -465,21 +465,22 @@ namespace Threads * run things in the background when there is no immediate need for the * result, or if there are other things that could well be done in parallel. * Whenever the result of that background task is needed, one can call either - * join() to just wait for the task to finish, or return_value() to obtain the - * value that was returned by the function that was run on that background - * task. + * Threads::Task::join() to just wait for the task to finish, or + * Threads::Task::return_value() to obtain the value that was returned by the + * function that was run on that background task. In both of these cases, one + * continues to reference the *operation* (namely, the Task object) that was + * in charge of computing the returned value. An alternative is to use the + * Threads::TaskResult class that references the *object* being computed + * rather than the task that computes it. * - * This class is conceptually similar to the + * This class is related to, but semantically not the same as, the * [`std::future`](https://en.cppreference.com/w/cpp/thread/future) class that * is returned by * [`std::async`](https://en.cppreference.com/w/cpp/thread/async) (which is * itself similar to what Threads::new_task() does). The principal conceptual - * difference is that one can only call `std::future::get()` once, whereas one - * can call Threads::Task::return_value() as many times as desired. It is, - * thus, comparable to the - * [`std::shared_future`](https://en.cppreference.com/w/cpp/thread/shared_future) - * class. However, `std::shared_future` can not be used for types that can not - * be copied -- a particular restriction for `std::unique_ptr`, for example. + * difference is that `std::future` references the *returned object* (like + * Threads::TaskResult) whereas the current object references the task that + * computes that result. * * @ingroup threads */ -- 2.39.5