Fix outdated documentation across multiple .dox files

libeigen/eigen!2148

Co-authored-by: Rasmus Munk Larsen <rmlarsen@gmail.com>

doc/TopicMultithreading.dox

@@ -4,11 +4,10 @@ namespace Eigen {
 
 \section TopicMultiThreading_MakingEigenMT Make Eigen run in parallel
 
-Some %Eigen's algorithms can exploit the multiple cores present in your hardware.
-To this end, it is enough to enable OpenMP on your compiler, for instance:
- - GCC: \c -fopenmp
- - ICC: \c -openmp
- - MSVC: check the respective option in the build properties.
+Some of %Eigen's algorithms can exploit the multiple cores present in your hardware.
+The primary mechanism is OpenMP. To enable it, pass the appropriate flag to your compiler:
+ - GCC/Clang: \c -fopenmp
+ - MSVC: \c /openmp (or check the respective option in the build properties)
 
 You can control the number of threads that will be used using either the OpenMP API or %Eigen's API using the following priority:
 \code
@@ -24,6 +23,14 @@ n = Eigen::nbThreads( );
 \endcode
 You can disable %Eigen's multi threading at compile time by defining the \link TopicPreprocessorDirectivesPerformance EIGEN_DONT_PARALLELIZE \endlink preprocessor token.
 
+\subsection TopicMultiThreading_ThreadPool Alternative: ThreadPool backend
+
+As an alternative to OpenMP, %Eigen supports a custom thread pool backend for GEMM operations.
+Define \c EIGEN_GEMM_THREADPOOL and use \c Eigen::setGemmThreadPool(Eigen::ThreadPool*) to
+provide a thread pool. OpenMP and \c EIGEN_GEMM_THREADPOOL are mutually exclusive.
+
+\subsection TopicMultiThreading_ParallelOps Parallelized operations
+
 Currently, the following algorithms can make use of multi-threading:
  - general dense matrix - matrix products
  - PartialPivLU
@@ -36,28 +43,14 @@ Currently, the following algorithms can make use of multi-threading:
 
 Indeed, the principle of hyper-threading is to run multiple threads (in most cases 2) on a single core in an interleaved manner.
 However, %Eigen's matrix-matrix product kernel is fully optimized and already exploits nearly 100% of the CPU capacity.
-Consequently, there is no room for running multiple such threads on a single core, and the performance would drops significantly because of cache pollution and other sources of overheads.
+Consequently, there is no room for running multiple such threads on a single core, and the performance would drop significantly because of cache pollution and other sources of overhead.
 At this stage of reading you're probably wondering why %Eigen does not limit itself to the number of physical cores?
 This is simply because OpenMP does not allow to know the number of physical cores, and thus %Eigen will launch as many threads as <i>cores</i> reported by OpenMP.
 
 \section TopicMultiThreading_UsingEigenWithMT Using Eigen in a multi-threaded application
 
-In the case your own application is multithreaded, and multiple threads make calls to %Eigen, then you have to initialize %Eigen by calling the following routine \b before creating the threads:
-\code
-#include <Eigen/Core>
-
-int main(int argc, char** argv)
-{
-  Eigen::initParallel();
-  
-  ...
-}
-\endcode
-
-\note With %Eigen 3.3, and a fully C++11 compliant compiler (i.e., <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Static_local_variables">thread-safe static local variable initialization</a>), then calling \c initParallel() is optional.
-
-\warning Note that all functions generating random matrices are \b not re-entrant nor thread-safe. Those include DenseBase::Random(), and DenseBase::setRandom() despite a call to `Eigen::initParallel()`. This is because these functions are based on `std::rand` which is not re-entrant.
-For thread-safe random generator, we recommend the use of c++11 random generators (\link DenseBase::NullaryExpr(Index, const CustomNullaryOp&) example \endlink) or `boost::random`.
+\warning Note that all functions generating random matrices are \b not re-entrant nor thread-safe. Those include DenseBase::Random(), and DenseBase::setRandom(). This is because these functions are based on \c std::rand which is not re-entrant.
+For thread-safe random generation, we recommend the use of C++11 random generators (\link DenseBase::NullaryExpr(Index, const CustomNullaryOp&) example \endlink).
 
 In the case your application is parallelized with OpenMP, you might want to disable %Eigen's own parallelization as detailed in the previous section.