1.. _Task_Scheduler_Init:
2
3Migrating from tbb::task_scheduler_init
4=======================================
5
6``tbb::task_scheduler_init`` was a multipurpose functionality in the previous versions of Threading
7Building Blocks (TBB). This section considers different use cases and how they can be covered with
8oneTBB.
9
10Managing the number of threads
11---------------------------------------
12
13Querying the default number of threads
14^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15
16* `oneapi::tbb::info::default_concurrency()
17  <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/info_namespace.html>`_
18  returns the maximum concurrency that will be created by *default* in implicit or explicit ``task_arena``.
19
20* `oneapi::tbb::this_task_arena::max_concurrency()
21  <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.html>`_
22  returns the maximum number of threads available for the parallel algorithms within the current context
23  (or *default* if an implicit arena is not initialized)
24
25* `oneapi::tbb::global_control::active_value(tbb::global_control::max_allowed_parallelism)
26  <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/global_control_cls.html>`_
27  returns the current limit of the thread pool (or *default* if oneTBB scheduler is not initialized)
28
29Setting the maximum concurrency
30^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
31
32* `task_arena(/* max_concurrency */)
33  <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.html>`_
34  limits the maximum concurrency of the parallel algorithm running inside ``task_arena``
35
36* `tbb::global_control(tbb::global_control::max_allowed_parallelism, /* max_concurrency */)
37  <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/global_control_cls.html>`_
38  limits the total number of oneTBB worker threads
39
40Examples
41^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42
43The default parallelism:
44
45.. code:: cpp
46
47    #include <oneapi/tbb/info.h>
48    #include <oneapi/tbb/parallel_for.h>
49    #include <oneapi/tbb/task_arena.h>
50    #include <cassert>
51
52    int main() {
53        // Get the default number of threads
54        int num_threads = oneapi::tbb::info::default_concurrency();
55
56        // Run the default parallelism
57        oneapi::tbb::parallel_for( /* ... */ [] {
58            // Assert the maximum number of threads
59            assert(num_threads == oneapi::tbb::this_task_arena::max_concurrency());
60        });
61
62        // Create the default task_arena
63        oneapi::tbb::task_arena arena;
64        arena.execute([]{
65            oneapi::tbb::parallel_for( /* ... */ [] {
66                // Assert the maximum number of threads
67                assert(num_threads == oneapi::tbb::this_task_arena::max_concurrency());
68            });
69        });
70
71        return 0;
72    }
73
74The limited parallelism:
75
76.. code:: cpp
77
78    #include <oneapi/tbb/info.h>
79    #include <oneapi/tbb/parallel_for.h>
80    #include <oneapi/tbb/task_arena.h>
81    #include <oneapi/tbb/global_control.h>
82    #include <cassert>
83
84    int main() {
85        // Create the custom task_arena with four threads
86        oneapi::tbb::task_arena arena(4);
87        arena.execute([]{
88            oneapi::tbb::parallel_for( /* ... */ [] {
89                // This arena is limited with for threads
90                assert(oneapi::tbb::this_task_arena::max_concurrency() == 4);
91            });
92        });
93
94        // Limit the number of threads to two for all oneTBB parallel interfaces
95        oneapi::tbb::global_control global_limit(oneapi::tbb::global_control::max_allowed_parallelism, 2);
96
97        // the default parallelism
98        oneapi::tbb::parallel_for( /* ... */ [] {
99            // No more than two threads is expected; however, tbb::this_task_arena::max_concurrency() can return a bigger value
100            int thread_limit = oneapi::tbb::global_control::active_value(oneapi::tbb::global_control::max_allowed_parallelism);
101            assert(thread_limit == 2);
102        });
103
104        arena.execute([]{
105            oneapi::tbb::parallel_for( /* ... */ [] {
106                // No more than two threads is expected; however, tbb::this_task_arena::max_concurrency() is four
107                int thread_limit = oneapi::tbb::global_control::active_value(oneapi::tbb::global_control::max_allowed_parallelism);
108                assert(thread_limit == 2);
109                assert(tbb::this_task_arena::max_concurrency() == 4);
110            });
111        });
112
113        return 0;
114    }
115
116Setting thread stack size
117---------------------------------------
118Use `oneapi::tbb::global_control(oneapi::tbb::global_control::thread_stack_size, /* stack_size */)
119<https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/global_control_cls.html>`_
120to set the stack size for oneTBB worker threads:
121
122.. code:: cpp
123
124    #include <oneapi/tbb/parallel_for.h>
125    #include <oneapi/tbb/global_control.h>
126
127    int main() {
128        // Set 16 MB of the stack size for oneTBB worker threads.
129        // Note that the stack size of the main thread should be configured in accordace with the
130        // system documentation, e.g. at application startup moment
131        oneapi::tbb::global_control global_limit(tbb::global_control::thread_stack_size, 16 * 1024 * 1024);
132
133        oneapi::tbb::parallel_for( /* ... */ [] {
134            // Create a big array in the stack
135            char big_array[10*1024*1024];
136        });
137
138        return 0;
139    }
140
141Terminating oneTBB scheduler
142---------------------------------------
143
144`task_scheduler_handle <https://oneapi-src.github.io/oneAPI-spec/spec/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.html>`_
145allows waiting for oneTBB worker threads completion:
146
147.. code:: cpp
148
149    #include <oneapi/tbb/global_control.h>
150    #include <oneapi/tbb/parallel_for.h>
151
152    int main() {
153        oneapi::tbb::task_scheduler_handle handle{tbb::attach{}};
154        // Do some parallel work here
155        oneapi::tbb::parallel_for(/* ... */);
156        oneapi::tbb::finalize(handle);
157        return 0;
158    }
159