diff --git a/doc/main/tbb_userguide/Flow_Graph_resource_tips.rst b/doc/main/tbb_userguide/Flow_Graph_resource_tips.rst index b202fc2275..27dd524c5b 100644 --- a/doc/main/tbb_userguide/Flow_Graph_resource_tips.rst +++ b/doc/main/tbb_userguide/Flow_Graph_resource_tips.rst @@ -14,4 +14,5 @@ in a flow graph. ../tbb_userguide/use_limiter_node ../tbb_userguide/use_concurrency_limits - ../tbb_userguide/create_token_based_system \ No newline at end of file + ../tbb_userguide/create_token_based_system + ../tbb_userguide/attach_flow_graph_to_arena \ No newline at end of file diff --git a/doc/main/tbb_userguide/attach_flow_graph_to_arena.rst b/doc/main/tbb_userguide/attach_flow_graph_to_arena.rst new file mode 100644 index 0000000000..d887d4b223 --- /dev/null +++ b/doc/main/tbb_userguide/attach_flow_graph_to_arena.rst @@ -0,0 +1,47 @@ +.. _attach_flow_graph_to_arena: + +Attach Flow Graph to an Arbitrary Task Arena +====================== + + +|short_name| ``task_arena`` interface provides mechanisms to guide tasks +execution within the arena by setting the preferred computation units, +restricting part of computation units, or limiting arena concurrency. In some +cases, you may want to apply such mechanisms when a flow graph executes. + +During its construction, a ``graph`` object attaches to the arena, in which the constructing +thread occupies a slot. + +This example shows how to set the most performant core type as the preferred one +for a graph execution: + + +.. literalinclude:: ./snippets/flow_graph_examples.cpp + :language: c++ + :start-after: /*begin_attach_to_arena_1*/ + :end-before: /*end_attach_to_arena_1*/ + + +A ``graph`` object can be reattached to a different ``task_arena`` by calling +the ``graph::reset()`` function. It reinitializes and reattaches the ``graph`` to +the task arena instance, inside which the ``graph::reset()`` method is executed. + +This example shows how to reattach existing graph to an arena with the most performant +core type as the preferred one for a work execution. Whenever a task is spawned on behalf +of the graph, it is spawned in the arena of a graph it is attached to, disregarding +the arena of the thread that the task is spawned from: + + +.. literalinclude:: ./snippets/flow_graph_examples.cpp + :language: c++ + :start-after: /*begin_attach_to_arena_2*/ + :end-before: /*end_attach_to_arena_2*/ + +See the following topics to learn more: + +.. toctree:: + :maxdepth: 4 + + ../tbb_userguide/Guiding_Task_Scheduler_Execution + ../tbb_userguide/work_isolation + diff --git a/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp b/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp new file mode 100644 index 0000000000..c1b97975c3 --- /dev/null +++ b/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp @@ -0,0 +1,76 @@ +/* + Copyright (c) 2022 Intel Corporation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/* Flow Graph Code Example for the Userguide. +*/ + +//! Enable extended task_arena constraints feature for supporting Intel Hybrid Technology +//! and Intel Hyper-Threading Technology. +#define TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION 1 + +#include +#include + +using namespace tbb::flow; + +//! Example shows how to set the most performant core type as the preferred one +//! for a graph execution. +static void flow_graph_attach_to_arena_1() { +/*begin_attach_to_arena_1*/ + std::vector core_types = tbb::info::core_types(); + tbb::task_arena arena( + tbb::task_arena::constraints{}.set_core_type(core_types.back()) + ); + + arena.execute( [&]() { + graph g; + function_node< int > f( g, unlimited, []( int ) { + /*the most performant core type is defined as preferred.*/ + } ); + f.try_put(1); + g.wait_for_all(); + } ); +/*end_attach_to_arena_1*/ +} + +//! Reattach existing graph to an arena with the most performant core type as +//! the preferred one for a work execution. +static void flow_graph_attach_to_arena_2() { +/*begin_attach_to_arena_2*/ + graph g; + function_node< int > f( g, unlimited, []( int ) { + /*the most performant core type is defined as preferred.*/ + } ); + + std::vector core_types = tbb::info::core_types(); + tbb::task_arena arena( + tbb::task_arena::constraints{}.set_core_type(core_types.back()) + ); + + arena.execute( [&]() { + g.reset(); + } ); + f.try_put(1); + g.wait_for_all(); +/*end_attach_to_arena_2*/ +} + +int main() { + flow_graph_attach_to_arena_1(); + flow_graph_attach_to_arena_2(); + + return 0; +}