From: bangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Wed, 30 Apr 2014 12:25:07 +0000 (+0000)
Subject: Clarify some of the function docs.
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8a769e10d31de62ff2fcdb307395355263214c81;p=dealii-svn.git

Clarify some of the function docs.

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

diff --git a/deal.II/include/deal.II/base/mpi.h b/deal.II/include/deal.II/base/mpi.h
index 5a734f16c7..6c1dff4bc9 100644
--- a/deal.II/include/deal.II/base/mpi.h
+++ b/deal.II/include/deal.II/base/mpi.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 2011 - 2013 by the deal.II authors
+// Copyright (C) 2011 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -274,15 +274,20 @@ namespace Utilities
        * Initialize MPI (and optionally PETSc) and set the number of threads
        * used by deal.II (and TBB) to the given parameter. If set to
        * numbers::invalid_unsigned_int, the number of threads is determined by
-       * TBB. When in doubt, set this value to 1.
+       * TBB. When in doubt, set this value to 1 since MPI jobs are typically
+       * run in a way where one has one MPI process per available processor
+       * core and there will be little CPU resources left to support multithreaded
+       * processes.
        *
-       * This will call MultithreadInfo::set_thread_limit() with @p
-       * max_num_threads, so the environment variable DEAL_II_NUM_THREADS will
-       * be respected.
+       * This function calls MultithreadInfo::set_thread_limit()
+       * unconditionally with @p max_num_threads . That function in turn also
+       * evaluates the environment variable DEAL_II_NUM_THREADS and the number
+       * of threads to be used will be the minimum of the argument passed here
+       * and the environment (if both are set).
        */
       MPI_InitFinalize (int    &argc,
                         char ** &argv,
-                        unsigned int max_num_threads);
+                        const unsigned int max_num_threads);
       /**
        * Destructor. Calls <tt>MPI_Finalize()</tt> in case this class owns the
        * MPI process.
@@ -304,7 +309,7 @@ namespace Utilities
        */
       void do_init(int    &argc,
                    char ** &argv,
-                   unsigned int max_num_threads);
+                   const unsigned int max_num_threads);
     };
 
     namespace internal
diff --git a/deal.II/source/base/mpi.cc b/deal.II/source/base/mpi.cc
index df1d360393..ca73d301d7 100644
--- a/deal.II/source/base/mpi.cc
+++ b/deal.II/source/base/mpi.cc
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 2005 - 2013 by the deal.II authors
+// Copyright (C) 2005 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -315,7 +315,7 @@ namespace Utilities
 
     MPI_InitFinalize::MPI_InitFinalize (int    &argc,
                                         char ** &argv,
-                                        unsigned int max_num_threads)
+                                        const unsigned int max_num_threads)
       :
       owns_mpi (true)
     {
@@ -337,7 +337,7 @@ namespace Utilities
     void
     MPI_InitFinalize::do_init(int    &argc,
                               char ** &argv,
-                              unsigned int max_num_threads)
+                              const unsigned int max_num_threads)
     {
       static bool constructor_has_already_run = false;
       Assert (constructor_has_already_run == false,
@@ -389,7 +389,8 @@ namespace Utilities
 
       constructor_has_already_run = true;
 
-      //set maximum number of threads:
+      // set maximum number of threads (also respecting the environment
+      // variable that the called function evaluates)
       multithread_info.set_thread_limit(max_num_threads);
     }