ground/gcs/src/libs/eigen/doc/TopicMultithreading.dox

   1 namespace Eigen {
   2
   3 /** \page TopicMultiThreading Eigen and multi-threading
   4
   5 \section TopicMultiThreading_MakingEigenMT Make Eigen run in parallel
   6
   7 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:
   8  * GCC: \c -fopenmp
   9  * ICC: \c -openmp
  10  * MSVC: check the respective option in the build properties.
  11 You can control the number of thread that will be used using either the OpenMP API or Eigen's API using the following priority:
  12 \code
  13  OMP_NUM_THREADS=n ./my_program
  14  omp_set_num_threads(n);
  15  Eigen::setNbThreads(n);
  16 \endcode
  17 Unless setNbThreads has been called, Eigen uses the number of threads specified by OpenMP. You can restore this behavior by calling \code setNbThreads(0); \endcode
  18 You can query the number of threads that will be used with:
  19 \code
  20 n = Eigen::nbThreads( );
  21 \endcode
  22 You can disable Eigen's multi threading at compile time by defining the EIGEN_DONT_PARALLELIZE preprocessor token.
  23
  24 Currently, the following algorithms can make use of multi-threading:
  25  - general dense matrix - matrix products
  26  - PartialPivLU
  27  - row-major-sparse * dense vector/matrix products
  28  - ConjugateGradient with \c Lower|Upper as the \c UpLo template parameter.
  29  - BiCGSTAB with a row-major sparse matrix format.
  30  - LeastSquaresConjugateGradient
  31
  32 \section TopicMultiThreading_UsingEigenWithMT Using Eigen in a multi-threaded application
  33
  34 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:
  35 \code
  36 #include <Eigen/Core>
  37
  38 int main(int argc, char** argv)
  39 {
  40   Eigen::initParallel();
  41
  42   ...
  43 }
  44 \endcode
  45
  46 \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.
  47
  48 \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 boost::random or c++11 random feature.
  49
  50 In the case your application is parallelized with OpenMP, you might want to disable Eigen's own parallization as detailed in the previous section.
  51
  52 */
  53
  54 }