From: Wolfgang Bangerth Date: Tue, 19 Nov 2013 13:54:40 +0000 (+0000) Subject: Provide more context in the documentation and link to a paper in preparation. X-Git-Tag: v8.1.0~250 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=84f08d155cd300582f3de1f089f37ae37613ded6;p=dealii.git Provide more context in the documentation and link to a paper in preparation. git-svn-id: https://svn.dealii.org/trunk@31705 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h index a4acb8b8c6..8117be9be1 100644 --- a/deal.II/doc/doxygen/headers/glossary.h +++ b/deal.II/doc/doxygen/headers/glossary.h @@ -1296,6 +1296,17 @@ Article{JK10, * @note The usual warning about the missing type safety of @p void pointers are * obviously in place here; responsibility for correctness of types etc * lies entirely with the user of the pointer. + * + * + *
@anchor workstream_paper %WorkStream paper
+ *
The "%WorkStream paper" is a paper by B. Turcksin, M. Kronbichler and W. Bangerth + * that discusses the design and implementation of WorkStream. WorkStream is, at its + * core, a design pattern, i.e., something that is used over and over in finite element + * codes and that can, consequently, be implemented generically. In particular, the + * paper lays out the motivation for this pattern and then proposes different ways + * of implementing it. It also compares the performance of different implementations. + * + * The paper is currently in preparation. *
* * diff --git a/deal.II/include/deal.II/base/graph_coloring.h b/deal.II/include/deal.II/base/graph_coloring.h index 86601c87b5..d8cc56d27a 100644 --- a/deal.II/include/deal.II/base/graph_coloring.h +++ b/deal.II/include/deal.II/base/graph_coloring.h @@ -491,6 +491,9 @@ namespace GraphColoring * conflict indicator sets have overlap will not be assigned to the same * color. * + * @note The algorithm used in this function is described in a paper by + * Turcksin, Kronbichler and Bangerth, see @ref workstream_paper . + * * @param[in] begin The first element of a range of iterators for which a * coloring is sought. * @param[in] end The element past the end of the range of iterators. diff --git a/deal.II/include/deal.II/base/work_stream.h b/deal.II/include/deal.II/base/work_stream.h index 330afcf1ce..71cadb7536 100644 --- a/deal.II/include/deal.II/base/work_stream.h +++ b/deal.II/include/deal.II/base/work_stream.h @@ -125,9 +125,9 @@ DEAL_II_NAMESPACE_OPEN * are considered unused and may be re-used for the next invokation of * the worker function, on this or another thread. * - * This class only really works in parallel when multithread mode was selected - * during deal.II configuration. Otherwise it simply works on each item - * sequentially. + * 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. * * @ingroup threads * @author Wolfgang Bangerth, 2007, 2008, 2009, 2013. Bruno Turcksin, 2013. @@ -149,7 +149,7 @@ namespace WorkStream * A namespace for the implementation of details of the WorkStream pattern * and function. This namespace holds classes that deal with the second * implementation described in the paper by Turcksin, Kronbichler and - * Bangerth. + * Bangerth (see @ref workstream_paper). * * Even though this implementation is slower than the third implementation * discussed in that paper, we need to keep it around for two reasons: @@ -693,7 +693,7 @@ namespace WorkStream * A namespace for the implementation of details of the WorkStream pattern * and function. This namespace holds classes that deal with the third * implementation described in the paper by Turcksin, Kronbichler and - * Bangerth. + * Bangerth (see @ref workstream_paper). */ namespace Implementation3 { @@ -781,7 +781,8 @@ namespace WorkStream * Pointer to a thread local variable identifying the scratch * and copy data objects this thread will use. The same considerations * apply as documented in the Implementation2::IteratorRangeToItemStream - * class as well as in the paper by Turcksin, Kronbichler and Bangerth. + * class as well as in the paper by Turcksin, Kronbichler and Bangerth + * (see @ref workstream_paper). */ Threads::ThreadLocalStorage *scratch_and_copy_data; @@ -924,7 +925,7 @@ namespace WorkStream * copy data objects each thread will use. The same is true as * discussed for the implementation in the * Implementation2::IteratorRangeToItemStream class and the paper - * by Turcksin, Kronbichler and Bangerth. + * by Turcksin, Kronbichler and Bangerth (see @ref workstream_paper). */ Threads::ThreadLocalStorage thread_local_scratch_and_copy; @@ -1144,7 +1145,8 @@ namespace WorkStream /** * This is one of two main functions of the WorkStream concept, doing work as * described in the introduction to this namespace. It corresponds to - * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth. + * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth + * (see @ref workstream_paper). * * This function that can be used for worker and copier objects that * are either pointers to non-member functions or objects that allow to be @@ -1257,7 +1259,8 @@ namespace WorkStream /** * This is one of two main functions of the WorkStream concept, doing work as * described in the introduction to this namespace. It corresponds to - * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth. + * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth, + * see @ref workstream_paper . * As such, it takes not a range of iterators described by a begin * and end iterator, but a "colored" graph of iterators where each * color represents cells for which writing the cell contributions into @@ -1265,7 +1268,8 @@ namespace WorkStream * are not neighbors). Each "color" is represented by std::vectors of cells. * The first argument to this function, a set of sets of cells (which are * represent as a vector of vectors, for efficiency), is typically - * constructed by calling GraphColoring::make_graph_coloring(). + * constructed by calling GraphColoring::make_graph_coloring(). See there + * for more information. * * This function that can be used for worker and copier objects that * are either pointers to non-member functions or objects that allow to be @@ -1375,7 +1379,7 @@ namespace WorkStream * This is a variant of one of the two main functions of the WorkStream * concept, doing work as described in the introduction to this namespace. * It corresponds to implementation 2 of the paper by Turcksin, Kronbichler - * and Bangerth. + * and Bangerth (see @ref workstream_paper). * * This is the function that can be used for worker and copier functions * that are member functions of a class.