Augment documentation.

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

diff --git a/deal.II/include/deal.II/base/utilities.h b/deal.II/include/deal.II/base/utilities.h
index 2632b4ece3ac54f13fa38003c50e9b454679143b..7093ff32f441a5b2bf89875defad0ade44837abd 100644 (file)
--- a/deal.II/include/deal.II/base/utilities.h
+++ b/deal.II/include/deal.II/base/utilities.h
@@ -166,6 +166,17 @@ namespace Utilities
    * normalized Gaussian probability
    * distribution centered around @p a and
    * with standard deviation @p sigma.
+   *
+   * This function is reentrant, i.e., it can safely be
+   * called from multiple threads at the same time. However, if
+   * so done, then there is no guarantee that each thread will
+   * get the same sequence of numbers every time. Rather, the
+   * produced sequence of random numbers will be apportioned to
+   * the different threads in non-deterministic ways. If this
+   * is a problem, for example for exactly reproducibility, then
+   * you need to use separate random number facilities for separate
+   * threads, rather than this global function. For example, the C++11
+   * standard offers such objects, as does BOOST.
    */
   double
   generate_normal_random_number (const double a,
@@ -782,4 +793,3 @@ namespace Utilities
 DEAL_II_NAMESPACE_CLOSE
 
 #endif
-

diff --git a/deal.II/source/base/utilities.cc b/deal.II/source/base/utilities.cc
index e9e95116984df367b237efa0da5fce6b0581f836..23834cd530c0bba70eb3e4defbcf8d0220a68be9 100644 (file)
--- a/deal.II/source/base/utilities.cc
+++ b/deal.II/source/base/utilities.cc
@@ -377,6 +377,11 @@ namespace Utilities
     if (sigma == 0)
       return a;
 
+    // we want to use rand(), but that function is not reentrant in a thread
+    // context. thus, use rand_r. this does not produce reproducible results
+    // between threads either, but at least it is reentrant. if you need
+    // an exactly reproducible sequence even in multithreaded contexts,
+    // then this is probably not the function to use.
 #ifdef HAVE_RAND_R
     static unsigned int seed = 0xabcd1234;
     const double y = 1.0*rand_r(&seed)/RAND_MAX;