| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 2000 - 2021 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
#ifndef dealii_multithread_info_h |
| 16 |
# define dealii_multithread_info_h |
| 17 |
//--------------------------------------------------------------------------- |
| 18 |
|
| 19 |
|
| 20 |
# include <deal.II/base/config.h> |
| 21 |
|
| 22 |
# include <deal.II/base/exceptions.h> |
| 23 |
# include <deal.II/base/types.h> |
| 24 |
|
| 25 |
# include <memory> |
| 26 |
|
| 27 |
# ifdef DEAL_II_WITH_TASKFLOW |
| 28 |
// forward declaration from <taskflow/taskflow.hpp> |
| 29 |
namespace tf |
| 30 |
{ |
| 31 |
class Executor; |
| 32 |
} |
| 33 |
# endif |
| 34 |
|
| 35 |
|
| 36 |
DEAL_II_NAMESPACE_OPEN |
| 37 |
|
| 38 |
/** |
| 39 |
* This class provides information about the system which may be of use in |
| 40 |
* multithreaded programs. At the moment this is just the number of CPUs. If |
| 41 |
* deal.II is compiled with multithreading support, some functions will use |
| 42 |
* multiple threads for their action. Currently the library supports both |
| 43 |
* thread-based and task-based parallelism. |
| 44 |
* @ref threads |
| 45 |
* describes the different uses of each. The default number of threads used |
| 46 |
* for task-based parallel methods is selected automatically by the Threading |
| 47 |
* Building Blocks library. See |
| 48 |
* @ref threads |
| 49 |
* for more information on this. Thread-based parallel methods need to |
| 50 |
* explicitly create threads and may want to use a number of threads that is |
| 51 |
* related to the number of CPUs in your system. The recommended number of |
| 52 |
* threads can be queried using MultithreadInfo::n_threads(), while the number |
| 53 |
* of cores in the system is returned by MultithreadInfo::n_cores(). |
| 54 |
* |
| 55 |
* @ingroup threads |
| 56 |
*/ |
| 57 |
class MultithreadInfo |
| 58 |
{ |
| 59 |
public: |
| 60 |
/** |
| 61 |
* Constructor. This constructor is deleted because no instance of |
| 62 |
* this class needs to be constructed (all members are static). |
| 63 |
*/ |
| 64 |
MultithreadInfo() = delete; |
| 65 |
|
| 66 |
/** |
| 67 |
* The number of CPUs in the system. |
| 68 |
* |
| 69 |
* This internally calls |
| 70 |
* [<code>std::thread::hardware_concurrency</code>](https://en.cppreference.com/w/cpp/thread/thread/hardware_concurrency) |
| 71 |
* but sets the result to 1 if the call returns an error. |
| 72 |
*/ |
| 73 |
static unsigned int |
| 74 |
n_cores(); |
| 75 |
|
| 76 |
/** |
| 77 |
* Return the number of threads to use. This is initially set to the number |
| 78 |
* of cores the system has (see n_cores()) but can be further restricted by |
| 79 |
* set_thread_limit() and the environment variable DEAL_II_NUM_THREADS. |
| 80 |
*/ |
| 81 |
static unsigned int |
| 82 |
n_threads(); |
| 83 |
|
| 84 |
/** |
| 85 |
* Return an estimate for the memory consumption, in bytes, of this object. |
| 86 |
* This is not exact (but will usually be close) because calculating the |
| 87 |
* memory usage of trees (e.g., <tt>std::map</tt>) is difficult. |
| 88 |
*/ |
| 89 |
static std::size_t |
| 90 |
memory_consumption(); |
| 91 |
|
| 92 |
/** |
| 93 |
* Set the maximum number of threads to be used to the minimum of the |
| 94 |
* environment variable DEAL_II_NUM_THREADS and the given argument (or its |
| 95 |
* default value). This affects the initialization of the TBB. If neither is |
| 96 |
* given, the default from TBB is used (based on the number of cores in the |
| 97 |
* system). |
| 98 |
* |
| 99 |
* This routine is executed automatically with the default argument before |
| 100 |
* your code in main() is running (using a static constructor). It is also |
| 101 |
* executed by Utilities::MPI::MPI_InitFinalize. Use the appropriate |
| 102 |
* argument of the constructor of Utilities::MPI::MPI_InitFinalize if you |
| 103 |
* have an MPI based code. |
| 104 |
*/ |
| 105 |
static void |
| 106 |
set_thread_limit( |
| 107 |
const unsigned int max_threads = numbers::invalid_unsigned_int); |
| 108 |
|
| 109 |
/** |
| 110 |
* Return if the TBB is running using a single thread either because of |
| 111 |
* thread affinity or because it is set via a call to set_thread_limit. This |
| 112 |
* is used in the PETScWrappers to avoid using the interface that is not |
| 113 |
* thread-safe. |
| 114 |
*/ |
| 115 |
static bool |
| 116 |
is_running_single_threaded(); |
| 117 |
|
| 118 |
/** |
| 119 |
* Make sure the multithreading API is initialized. This normally does not |
| 120 |
* need to be called in usercode. |
| 121 |
*/ |
| 122 |
static void |
| 123 |
initialize_multithreading(); |
| 124 |
|
| 125 |
|
| 126 |
# ifdef DEAL_II_WITH_TASKFLOW |
| 127 |
/** |
| 128 |
* Return a reference to the global Executor from taskflow. |
| 129 |
* |
| 130 |
* The Executor is set to use n_threads() worker threads that you can |
| 131 |
* control using set_thread_limit() and the DEAL_II_NUM_THREADS environment |
| 132 |
* variable. |
| 133 |
*/ |
| 134 |
static tf::Executor & |
| 135 |
get_taskflow_executor(); |
| 136 |
# endif |
| 137 |
|
| 138 |
private: |
| 139 |
/** |
| 140 |
* Variable representing the maximum number of threads. |
| 141 |
*/ |
| 142 |
static unsigned int n_max_threads; |
| 143 |
|
| 144 |
# ifdef DEAL_II_WITH_TASKFLOW |
| 145 |
/** |
| 146 |
* Store a taskflow Executor that is constructed with N workers (from |
| 147 |
* set_thread_limit). |
| 148 |
*/ |
| 149 |
static std::unique_ptr<tf::Executor> executor; |
| 150 |
# endif |
| 151 |
}; |
| 152 |
|
| 153 |
|
| 154 |
|
| 155 |
//--------------------------------------------------------------------------- |
| 156 |
DEAL_II_NAMESPACE_CLOSE |
| 157 |
// end of #ifndef dealii_multithread_info_h |
| 158 |
#endif |
| 159 |
//--------------------------------------------------------------------------- |