From: bangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Tue, 8 Jun 2010 16:41:49 +0000 (+0000)
Subject: Commit Michael Rapson's patch for better threading documentation.
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f55a9ecaf90e33f2b2dc63ee8451ef8582df4b4d;p=dealii-svn.git

Commit Michael Rapson's patch for better threading documentation.

git-svn-id: https://svn.dealii.org/trunk@21180 0785d39b-7218-0410-832d-ea1e28bc413d
---

diff --git a/deal.II/base/include/base/multithread_info.h b/deal.II/base/include/base/multithread_info.h
index f6873ed2a1..ace22c2036 100644
--- a/deal.II/base/include/base/multithread_info.h
+++ b/deal.II/base/include/base/multithread_info.h
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006 by the deal.II authors
+//    Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2010 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -24,11 +24,16 @@ DEAL_II_NAMESPACE_OPEN
  * This class provides information about the system which may be of
  * use in multithreaded programs.  At the moment this is just the
  * number of cpus. If deal.II is compiled with multithreading support,
- * some functions will use multiple threads for their action, and will
- * use the member variable <tt>n_default_threads</tt> of this class as the
- * default number of threads to start.  This variable
- * <tt>n_default_threads</tt> is set to the number of CPUs by default, but
- * can be adjusted by the user to fit the requirements.
+ * some functions will use multiple threads for their action. Currently
+ * the library supports both thread-based and task-based parallelism. @ref threads
+ * describes the different uses of each. Thread-based parallel methods will
+ * use the member variable n_default_threads of this class as a guide to the
+ * number of threads to start.  This variable
+ * n_default_threads is set to the number of CPUs by default, but
+ * can be adjusted by the user to fit the requirements. The default number of 
+ * threads used for task-based parallel methods is selected automatically
+ * by the Threading Building
+ * Blocks library. See @ref threads for more information on this.
  *
  * @ingroup threads
  * @author Thomas Richter, Wolfgang Bangerth, 2000
diff --git a/deal.II/doc/doxygen/headers/multithreading.h b/deal.II/doc/doxygen/headers/multithreading.h
index e29088162b..d671c516cd 100644
--- a/deal.II/doc/doxygen/headers/multithreading.h
+++ b/deal.II/doc/doxygen/headers/multithreading.h
@@ -58,6 +58,7 @@
  *  <li> @ref MTComplexLoops "Abstractions for tasks: More complex loops"
  *  <li> @ref MTWorkStream "Abstractions for tasks: Work streams"
  *  <li> @ref MTThreads "Thread-based parallelism"
+ *  <li> @ref MTTaskThreads "Controlling the number of threads used for tasks"
  * </ol> </td> </tr> </table>
  *
  *
@@ -1101,4 +1102,40 @@
  * return value of a finished thread using Threads::Thread::return_value(),
  * and you can group threads into a Threads::ThreadGroup object and wait for
  * all of them to finish.
+ *
+ *
+ * @anchor MTTaskThreads
+ * <h3>Controlling the number of threads used for tasks</h3>
+ * As mentioned earlier, deal.II does not implement scheduling tasks to
+ * threads or even starting threads itself. The TBB library does a good job at
+ * deciding how many threads to use and they do not recommend setting the
+ * number of threads explicitly. However, on large symmetric multiprocessing
+ * (SMP) machines, especially ones with a resource/job manager or on systems
+ * on which access to some parts of the memory is possible but very expensive
+ * for processors far away (e.g. large NUMA SMP machines), it may be necessary
+ * to explicitly set the number of threads to prevent the TBB from using too
+ * many CPUs. In this case the following commands can be used:
+ * @code
+   #include <tbb/task_scheduler_init.h>
+
+   // In the program, before any task-based parallelism is reached.
+   // Early in the main method is a good place to call this:
+   tbb::task_scheduler_init init(n_desired_threads + 1); 
+ * @endcode
+ * The method of setting the number of threads relies on this call to
+ * <code>task_scheduler_init</code> occurring before any other calls to the
+ * TBB functions.  If this call is first, it will set the number of threads
+ * used by TBB for the remainder of the program.  Notice that the call starts
+ * one less thread than the argument, since the main thread is counted. If
+ * this method does not seem successful (gdb can be used to see when and how
+ * many threads are started), ensure that the call is early enough in the
+ * program (for example right at the start of <code>main()</code>), and check
+ * that there are no other libraries starting threads.
+ *
+ * Note that a small number of places inside deal.II also uses thread-based
+ * parallelism controlled by MultithreadInfo::n_default_threads
+ * generally. Under some circumstances, deal.II also calls the BLAS library
+ * which may sometimes also start threads of its own. You will have to consult
+ * the documentation of your BLAS installation to determine how to set the
+ * number of threads for these operations.
  */