Intel® oneAPI Threading Building Blocks Developer Guide and API Reference

Download PDF
ID 772616
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
Intel(R) oneAPI Threading Building Blocks (oneTBB) Developer Guide and API Reference
Intel(R) oneAPI Threading Building Blocks (oneTBB) Developer Guide and API Reference x
Getting Help and Support Notational Conventions Introduction oneTBB Benefits Known Limitations oneTBB Developer Guide oneTBB API Reference Notices and Disclaimers
oneTBB Developer Guide x
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 Invoke a Callable Object Appendix A Costs of Time Slicing Appendix B Mixing With Other Threading Packages References
Package Contents x
Debug Versus Release Libraries Scalable Memory Allocator Windows* Linux* macOS*
Parallelizing Simple Loops x
Initializing and Terminating the Library parallel_for parallel_reduce Advanced Example Advanced Topic: Other Kinds of Iteration Spaces
parallel_for x
Lambda Expressions Automatic Chunking Controlling Chunking Bandwidth and Cache Affinity Partitioner Summary
Parallelizing Complex Loops x
Cook Until Done: parallel_for_each Working on the Assembly Line: parallel_pipeline Summary of Loops and Pipelines
Working on the Assembly Line: parallel_pipeline x
Using Circular Buffers Throughput of pipeline Non-Linear Pipelines
Parallelizing Data Flow and Dependence Graphs x
Parallelizing Data Flow and Dependency Graphs Basic Flow Graph Concepts Graph Application Categories Predefined Node Types Flow Graph Tips and Tricks Estimating Flow Graph Performance
Basic Flow Graph Concepts x
Flow Graph Basics: Graph Object Flow Graph Basics: Nodes Flow Graph Basics: Edges Flow Graph Basics: Mapping Nodes to Tasks Flow Graph Basics: Message Passing Protocol Flow Graph Basics: Single-push vs. Broadcast-push Flow Graph Basics: Buffering and Forwarding Flow Graph Basics: Reservation
Graph Application Categories x
Data Flow Graph Dependence Graph
Flow Graph Tips and Tricks x
Flow Graph Tips for Waiting for and Destroying a Flow Graph Flow Graph Tips on Making Edges Flow Graph Tips on Nested Parallelism Flow Graph Tips for Limiting Resource Consumption Flow Graph Tips for Exception Handling and Cancellation
Flow Graph Tips for Waiting for and Destroying a Flow Graph x
Always Use wait_for_all() Avoid Dynamic Node Removal Destroying Graphs That Run Outside the Main Thread
Flow Graph Tips on Making Edges x
Use make_edge and remove_edge Sending to One or Multiple Successors Communication Between Graphs Using input_node Avoiding Data Races
Flow Graph Tips on Nested Parallelism x
Use Nested Algorithms to Increase Scalability Use Nested Flow Graphs
Flow Graph Tips for Limiting Resource Consumption x
Using limiter_node Use Concurrency Limits Create a Token-Based System Attach Flow Graph to an Arbitrary Task Arena
Attach Flow Graph to an Arbitrary Task Arena x
Guiding Task Scheduler Execution Work Isolation
Flow Graph Tips for Exception Handling and Cancellation x
Catching Exceptions Inside the Node that Throws the Exception Cancel a Graph Explicitly Use graph::reset() to Reset a Canceled Graph Canceling Nested Parallelism
Exceptions and Cancellation x
Cancellation Without An Exception Cancellation and Nested Parallelism
Containers x
concurrent_hash_map concurrent_vector Concurrent Queue Classes Summary of Containers
concurrent_hash_map x
More on HashCompare
Concurrent Queue Classes x
Iterating Over a Concurrent Queue for Debugging When Not to Use Queues
Mutual Exclusion x
Mutex Flavors Reader Writer Mutexes Upgrade/Downgrade Lock Pathologies
Memory Allocation x
Which Dynamic Libraries to Use Configuring the Memory Allocator Automatically Replacing malloc and Other C/C++ Functions for Dynamic Memory Allocation
Automatically Replacing malloc and Other C/C++ Functions for Dynamic Memory Allocation x
Windows* OS C/C++ Dynamic Memory Interface Replacement Linux* OS C/C++ Dynamic Memory Interface Replacement
The Task Scheduler x
Task-Based Programming When Task-Based Programming Is Inappropriate How Task Scheduler Works Task Scheduler Bypass Guiding Task Scheduler Execution
Design Patterns x
Agglomeration Elementwise Odd-Even Communication Wavefront Reduction Divide and Conquer GUI Thread Non-Preemptive Priorities Lazy Initialization Local Serializer Fenced Data Transfer Reference Counting General References
Migrating from Threading Building Blocks (TBB) x
Migrating from tbb::task_scheduler_init Migrating from low-level task API Mixing two runtimes
oneTBB API Reference x
parallel_for_each Body semantics and requirements Description parallel_sort ranges interface extension TBB_malloc_replacement_log Function Type-specified message keys for join_node Scalable Memory Pools Helper Functions for Expressing Graphs concurrent_lru_cache task_group extensions The customizing mutex type for concurrent_hash_map
Scalable Memory Pools x
memory_pool fixed_pool memory_pool_allocator
Helper Functions for Expressing Graphs x
Constructors for Flow Graph nodes follows and precedes function templates make_node_set function template make_edges function template
Intel(R) oneAPI Threading Building Blocks (oneTBB) Developer Guide and API Reference

parallel_for_each Body semantics and requirements

Description

This page clarifies ParallelForEachBody named requirements for tbb::parallel_for_each algorithm specification.

namespace oneapi {
    namespace tbb {

        template <typaname InputIterator, typename Body>
        void parallel_for_each( InputIterator first, InputIterator last, Body body ); // overload (1)
        template <typename InputIterator, typename Body>
        void parallel_for_each( InputIterator first, InputIterator last, Body body, task_group_context& group ); // overload (2)

        template <typename Container, typename Body>
        void parallel_for_each( Container& c, Body body ); // overload (3)
        template <typename Container, typename Body>
        void parallel_for_each( Container& c, Body body, task_group_context& group ); // overload (4)

        template <typename Container, typename Body>
        void parallel_for_each( const Container& c, Body body ); // overload (5)
        template <typename Container, typename Body>
        void parallel_for_each( const Container& c, Body body, task_group_context& group ); // overload (6)

    } // namespace tbb
} // namespace oneapi

Terms

  • iterator determines the type of the iterator passed into parallel_for_each algorithm (which is InputIterator for overloads (1) and (2) and decltype(std::begin(c)) for overloads (3) - (6))

  • value_type - the type typename std::iterator_traits<iterator>::value_type

  • reference - the type typename std::iterator_traits<iterator>::reference.

Requirements for different iterator types

If the iterator satisfies Input iterator named requirements from [input.iterators] ISO C++ Standard section and do not satisfies Forward iterator named requirements from [forward.iterators] ISO C++ Standard section, tbb::parallel_for_each requires the execution of the body with an object of type const value_type& or value_type&& to be well-formed. If both forms are well-formed, an overload with rvalue reference will be preferred.

CAUTION:
If the Body only takes non-const lvalue reference to value_type, named requirements above are violated and the program can be ill-formed.

If the iterator satisfies Forward iterator named requirements from [forward.iterators] ISO C++ Standard section, tbb::parallel_for_each requires the execution of the body with an object of type reference to be well-formed.

Requirements for Body with feeder argument

Additional elements submitted into tbb::parallel_for_each through the feeder::add passes to the Body as rvalues and therefore the corresponding execution of the Body is required to be well-formed.

Level Two Title