* 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.
* 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.
*
* 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
* 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
*
* 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
*
* 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
projects / dealii.git / commitdiff