]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Better document WorkStream and mesh_loop(). 9158/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Mon, 9 Dec 2019 17:51:58 +0000 (10:51 -0700)
committerWolfgang Bangerth <bangerth@colostate.edu>
Mon, 9 Dec 2019 17:51:58 +0000 (10:51 -0700)
include/deal.II/base/work_stream.h
include/deal.II/meshworker/mesh_loop.h

index 25389627811d4fb82c9476f5c6634fe3b38deeb6..228b2b4f0aa32393be25331682f090d709de5809 100644 (file)
@@ -126,7 +126,11 @@ DEAL_II_NAMESPACE_OPEN
  * Once an item is processed by the copier, it is deleted and the ScratchData
  * and CopyData objects that were used in its computation are considered
  * unused and may be re-used for the next invocation of the worker function,
- * on this or another thread.
+ * on this or another thread. However, the WorkStream functions make no
+ * attempt to reset these objects to any kind of pristine state -- a worker
+ * should assume that the CopyData object it gets handed has prior content
+ * and clear it first in whatever manner seems appropriate, before putting
+ * content into it that can later be processed again by the copier.
  *
  * The member variables in ScratchData and CopyData can be accessed
  * independently of other concurrent uses of copies of these data structures.
@@ -139,7 +143,13 @@ DEAL_II_NAMESPACE_OPEN
  * CopyData can be resized in accordance with the number of local DoFs on the
  * current cell.
  *
- * The functions in this namespace only really work in parallel when
+ * @note For integration over cells and faces, it is often useful to use
+ * methods more specific to the task than the current function (which doesn't
+ * care whether the iterators are over cells, vector elements, or any other
+ * kind of range). An implementation of an interface specifically suited to
+ * integration is the MeshWorker::mesh_loop() function.
+ *
+ * @note The functions in this namespace only really work in parallel when
  * multithread mode was selected during deal.II configuration. Otherwise they
  * simply work on each item sequentially.
  *
index 8c8d79f7cc8ae1aa07116688c44c0e59ba37aa2f..d301f6f665a3b5c39d17bae2fd6225770566d9ec 100644 (file)
@@ -120,7 +120,7 @@ namespace MeshWorker
    * identify the corresponding subface on either the current or the neighbor
    * faces.
    *
-   * This method externalises that logic (which is independent from user codes)
+   * This method externalizes that logic (which is independent from user codes)
    * and separates the assembly of face terms (internal faces, boundary faces,
    * or faces between different subdomain ids on parallel computations) from
    * the assembling on cells, allowing the user to specify two additional
@@ -128,7 +128,7 @@ namespace MeshWorker
    * are called automatically in each @p cell, according to the specific
    * AssembleFlags @p flags that are passed. The @p cell_worker is passed the
    * cell identifier, a ScratchData object, and a CopyData object, following
-   * the same principles of WorkStream::run. Internally the function passes to
+   * the same principles of WorkStream::run(). Internally the function passes to
    * @p boundary_worker, in addition to the above, also a @p face_no parameter
    * that identifies the face on which the integration should be performed. The
    * @p face_worker instead needs to identify the current face unambiguously
@@ -155,7 +155,14 @@ namespace MeshWorker
    *
    * The two data types ScratchData and CopyData need to have a working copy
    * constructor. ScratchData is only used in the worker function, while
-   * CopyData is the object passed from the worker to the copier.
+   * CopyData is the object passed from the worker to the copier. The CopyData
+   * object is reset to the value provided to this function every time this
+   * function visits a new cell (where it then calls the cell and face
+   * workers). In other words, no state carries over between calling the
+   * `copier` on one cell and the `cell_worker`/`face_worker`/`boundary_worker`
+   * functions on the next cell, and user code needs not reset the copy
+   * object either at the beginning of the cell integration or end of the
+   * copy operation.
    *
    * The queue_length argument indicates the number of items that can be live at
    * any given time. Each item consists of chunk_size elements of the input
@@ -164,7 +171,7 @@ namespace MeshWorker
    *
    * If your data objects are large, or their constructors are expensive, it is
    * helpful to keep in mind that queue_length copies of the ScratchData object
-   * and queue_length*chunk_size copies of the CopyData object are generated.
+   * and `queue_length*chunk_size` copies of the CopyData object are generated.
    *
    * @note More information about requirements on template types and meaning
    * of @p queue_length and @p chunk_size can be found in the documentation of the

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.