From f55a9ecaf90e33f2b2dc63ee8451ef8582df4b4d Mon Sep 17 00:00:00 2001 From: bangerth Date: Tue, 8 Jun 2010 16:41:49 +0000 Subject: [PATCH] Commit Michael Rapson's patch for better threading documentation. git-svn-id: https://svn.dealii.org/trunk@21180 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/base/include/base/multithread_info.h | 17 +++++---- deal.II/doc/doxygen/headers/multithreading.h | 37 ++++++++++++++++++++ 2 files changed, 48 insertions(+), 6 deletions(-) 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 n_default_threads of this class as the - * default 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. + * 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 @@ *
  • @ref MTComplexLoops "Abstractions for tasks: More complex loops" *
  • @ref MTWorkStream "Abstractions for tasks: Work streams" *
  • @ref MTThreads "Thread-based parallelism" + *
  • @ref MTTaskThreads "Controlling the number of threads used for tasks" * * * @@ -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 + *

    Controlling the number of threads used for tasks

    + * 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 + + // 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 + * task_scheduler_init 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 main()), 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. */ -- 2.39.5