From: Wolfgang Bangerth Date: Mon, 21 Jul 2014 12:58:42 +0000 (-0500) Subject: Augment documentation. X-Git-Tag: v8.2.0-rc1~265^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a8223b63ec6f0b087e33ef80a6a8b8605485f2ab;p=dealii.git Augment documentation. The documentation of MultithreadInfo was unintelligible. It was also incomplete in some places. --- diff --git a/include/deal.II/base/multithread_info.h b/include/deal.II/base/multithread_info.h index b1e3066a60..6d364072c3 100644 --- a/include/deal.II/base/multithread_info.h +++ b/include/deal.II/base/multithread_info.h @@ -1,7 +1,7 @@ // --------------------------------------------------------------------- // $Id$ // -// Copyright (C) 2000 - 2013 by the deal.II authors +// Copyright (C) 2000 - 2014 by the deal.II authors // // This file is part of the deal.II library. // @@ -26,22 +26,23 @@ 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. 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. - * To set n_default_threads add the following at the start of your main(): + * 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. Currently the library supports both + * thread-based and task-based parallelism. @ref threads describes the + * different uses of each. 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. Thread-based + * parallel methods need to explicitly created threads and may want to use a + * number of threads that is related to the number of CPUs in your + * system. This can be queried using the variable * - * multithread_info.n_default_threads=1; + * multithread_info.n_cpus; + * + * of a global variable multithread_info of this class that, or using + * + * multithread_info.n_threads(); * * * @ingroup threads @@ -80,20 +81,30 @@ public: const unsigned int n_cpus; /** - * The number of threads to use as - * a default value for all functions - * that support multithreading. - * At start time this is n_cpus or - * one, if detection of the number - * of CPUs is not possible. + * The number of threads to use as a default value for all functions that + * support multithreading. At start time this is n_cpus or one, if + * detection of the number of CPUs is not possible. + * + * This variable used to be the mechanism by which many parts of the library + * determined how many threads to use, for example when assembling matrices + * in MatrixCreator or generating output in DataOut. To this end, + * n_default_threads is set to n_cpus at the start of the program, but used + * programs could set it to a different value in their main() + * function. However, since almost all of deal.II has now been converted to + * a task-based parallelism model, this variable is no longer used in the + * library. Instead, the task scheduling methods use the n_threads() + * function as a guide to how many threads to use, and the current variable + * is now deprecated. * - * @deprecated: use set_thread_limit() instead. + * @deprecated: Use n_threads() to query the number of threads to use (if + * you wanted to read this variable), and set_thread_limit() to limit it (if + * you wanted to write to it). */ unsigned int n_default_threads DEAL_II_DEPRECATED; /** - * Returns the number of threads to use. This is governed by the number - * of cores the system has (n_cpus) and can be further restricted by + * Returns the number of threads to use. This is initially set to the number + * of cores the system has (n_cpus) but can be further restricted by * set_thread_limit(). */ unsigned int n_threads() const;