From adab6bc862d92552570c8317697b74cef370d539 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 9 Dec 2019 10:51:58 -0700 Subject: [PATCH] Better document WorkStream and mesh_loop(). --- include/deal.II/base/work_stream.h | 14 ++++++++++++-- include/deal.II/meshworker/mesh_loop.h | 15 +++++++++++---- 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/include/deal.II/base/work_stream.h b/include/deal.II/base/work_stream.h index 2538962781..228b2b4f0a 100644 --- a/include/deal.II/base/work_stream.h +++ b/include/deal.II/base/work_stream.h @@ -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. * diff --git a/include/deal.II/meshworker/mesh_loop.h b/include/deal.II/meshworker/mesh_loop.h index 8c8d79f7cc..d301f6f665 100644 --- a/include/deal.II/meshworker/mesh_loop.h +++ b/include/deal.II/meshworker/mesh_loop.h @@ -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 -- 2.39.5