Debian Codegraph @

include/deal.II/base/multithread_info.h

raw
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 //---------------------------------------------------------------------------