Visible to Intel only — GUID: GUID-EC92848C-6B3B-40A3-BD67-3D5F19029CC6
Package Contents
Parallelizing Simple Loops
Parallelizing Complex Loops
Parallelizing Data Flow and Dependence Graphs
Work Isolation
Exceptions and Cancellation
Containers
Mutual Exclusion
Timing
Memory Allocation
The Task Scheduler
Design Patterns
Migrating from Threading Building Blocks (TBB)
Constrained APIs
Appendix A Costs of Time Slicing
Appendix B Mixing With Other Threading Packages
References
oneapi::tbb::info namespace
parallel_for_each Body semantics and requirements
parallel_sort ranges interface extension
Type-specified message keys for join_node
Scalable Memory Pools
Helper Functions for Expressing Graphs
concurrent_lru_cache
task_arena::constraints extensions
oneapi::tbb::info namespace extensions
task_group extensions
The customizing mutex type for concurrent_hash_map
Visible to Intel only — GUID: GUID-EC92848C-6B3B-40A3-BD67-3D5F19029CC6
Migrating from tbb::task_scheduler_init
tbb::task_scheduler_init was a multipurpose functionality in the previous versions of Threading Building Blocks (TBB). This section considers different use cases and how they can be covered with oneTBB.
Managing the number of threads
Querying the default number of threads
oneapi::tbb::info::default_concurrency() returns the maximum concurrency that will be created by default in implicit or explicit task_arena.
oneapi::tbb::this_task_arena::max_concurrency() returns the maximum number of threads available for the parallel algorithms within the current context (or default if an implicit arena is not initialized)
oneapi::tbb::global_control::active_value(tbb::global_control::max_allowed_parallelism) returns the current limit of the thread pool (or default if oneTBB scheduler is not initialized)
Setting the maximum concurrency
task_arena(/* max_concurrency */) limits the maximum concurrency of the parallel algorithm running inside task_arena
tbb::global_control(tbb::global_control::max_allowed_parallelism, /* max_concurrency */) limits the total number of oneTBB worker threads
Examples
The default parallelism:
#include <oneapi/tbb/info.h>
#include <oneapi/tbb/parallel_for.h>
#include <oneapi/tbb/task_arena.h>
#include <cassert>
int main() {
// Get the default number of threads
int num_threads = oneapi::tbb::info::default_concurrency();
// Run the default parallelism
oneapi::tbb::parallel_for( /* ... */ [] {
// Assert the maximum number of threads
assert(num_threads == oneapi::tbb::this_task_arena::max_concurrency());
});
// Create the default task_arena
oneapi::tbb::task_arena arena;
arena.execute([]{
oneapi::tbb::parallel_for( /* ... */ [] {
// Assert the maximum number of threads
assert(num_threads == oneapi::tbb::this_task_arena::max_concurrency());
});
});
return 0;
}
The limited parallelism:
#include <oneapi/tbb/info.h>
#include <oneapi/tbb/parallel_for.h>
#include <oneapi/tbb/task_arena.h>
#include <oneapi/tbb/global_control.h>
#include <cassert>
int main() {
// Create the custom task_arena with four threads
oneapi::tbb::task_arena arena(4);
arena.execute([]{
oneapi::tbb::parallel_for( /* ... */ [] {
// This arena is limited with for threads
assert(oneapi::tbb::this_task_arena::max_concurrency() == 4);
});
});
// Limit the number of threads to two for all oneTBB parallel interfaces
oneapi::tbb::global_control global_limit(oneapi::tbb::global_control::max_allowed_parallelism, 2);
// the default parallelism
oneapi::tbb::parallel_for( /* ... */ [] {
// No more than two threads is expected; however, tbb::this_task_arena::max_concurrency() can return a bigger value
int thread_limit = oneapi::tbb::global_control::active_value(oneapi::tbb::global_control::max_allowed_parallelism);
assert(thread_limit == 2);
});
arena.execute([]{
oneapi::tbb::parallel_for( /* ... */ [] {
// No more than two threads is expected; however, tbb::this_task_arena::max_concurrency() is four
int thread_limit = oneapi::tbb::global_control::active_value(oneapi::tbb::global_control::max_allowed_parallelism);
assert(thread_limit == 2);
assert(tbb::this_task_arena::max_concurrency() == 4);
});
});
return 0;
}
Setting thread stack size
Use oneapi::tbb::global_control(oneapi::tbb::global_control::thread_stack_size, /* stack_size */) to set the stack size for oneTBB worker threads:
#include <oneapi/tbb/parallel_for.h>
#include <oneapi/tbb/global_control.h>
int main() {
// Set 16 MB of the stack size for oneTBB worker threads.
// Note that the stack size of the main thread should be configured in accordace with the
// system documentation, e.g. at application startup moment
oneapi::tbb::global_control global_limit(tbb::global_control::thread_stack_size, 16 * 1024 * 1024);
oneapi::tbb::parallel_for( /* ... */ [] {
// Create a big array in the stack
char big_array[10*1024*1024];
});
return 0;
}
Terminating oneTBB scheduler
task_scheduler_handle Class allows waiting for oneTBB worker threads completion:
#include <oneapi/tbb/global_control.h>
#include <oneapi/tbb/parallel_for.h>
int main() {
oneapi::tbb::task_scheduler_handle handle{tbb::attach{}};
// Do some parallel work here
oneapi::tbb::parallel_for(/* ... */);
oneapi::tbb::finalize(handle);
return 0;
}