From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 18 Oct 2019 16:51:11 +0000 (-0600)
Subject: Be more explicit about the Copied argument to WorkStream::run().
X-Git-Tag: v9.2.0-rc1~969^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=72e1bb545b3f5848f052ed9299d63e5589019f7b;p=dealii.git

Be more explicit about the Copied argument to WorkStream::run().
---

diff --git a/include/deal.II/base/work_stream.h b/include/deal.II/base/work_stream.h
index c2664c39e2..31e06c848b 100644
--- a/include/deal.II/base/work_stream.h
+++ b/include/deal.II/base/work_stream.h
@@ -929,8 +929,16 @@ namespace WorkStream
    * are generated.
    *
    * @note In case the copier does not do anything, pass
-   * <code>std::function<void(const CopyData&)>()</code> as @p copier to make sure
-   * a more efficient algorithm is used internally.
+   * `std::function<void(const CopyData &)>()` as @p copier to make sure
+   * a more efficient algorithm is used internally. It is important, however,
+   * to recognize that the empty function object created above is *not*
+   * the same as a lambda function with an empty body,
+   * `[](const CopyData &) {}` -- from the perspective of this function,
+   * there is no way to recognize whether a lambda function provided as
+   * a copier does something or does not do something in its body,
+   * and so it needs to be copied. On the other hand, a default-constructed
+   * `std::function` object *can* be recognized, and is then used to select
+   * a more efficient algorithm.
    */
   template <typename Worker,
             typename Copier,
@@ -982,8 +990,16 @@ namespace WorkStream
    * are generated.
    *
    * @note In case the copier does not do anything, pass
-   * <code>std::function<void(const CopyData&)>()</code> as @p copier to make sure
-   * a more efficient algorithm is used internally.
+   * `std::function<void(const CopyData &)>()` as @p copier to make sure
+   * a more efficient algorithm is used internally. It is important, however,
+   * to recognize that the empty function object created above is *not*
+   * the same as a lambda function with an empty body,
+   * `[](const CopyData &) {}` -- from the perspective of this function,
+   * there is no way to recognize whether a lambda function provided as
+   * a copier does something or does not do something in its body,
+   * and so it needs to be copied. On the other hand, a default-constructed
+   * `std::function` object *can* be recognized, and is then used to select
+   * a more efficient algorithm.
    */
   template <typename Worker,
             typename Copier,
@@ -1276,8 +1292,16 @@ namespace WorkStream
    * are generated.
    *
    * @note In case the copier does not do anything, pass
-   * <code>std::function<void(const CopyData&)>()</code> as @p copier to make sure
-   * a more efficient algorithm is used internally.
+   * `std::function<void(const CopyData &)>()` as @p copier to make sure
+   * a more efficient algorithm is used internally. It is important, however,
+   * to recognize that the empty function object created above is *not*
+   * the same as a lambda function with an empty body,
+   * `[](const CopyData &) {}` -- from the perspective of this function,
+   * there is no way to recognize whether a lambda function provided as
+   * a copier does something or does not do something in its body,
+   * and so it needs to be copied. On the other hand, a default-constructed
+   * `std::function` object *can* be recognized, and is then used to select
+   * a more efficient algorithm.
    */
   template <typename MainClass,
             typename Iterator,