Document a way to flow graph can be attached to arbitrary task_arena

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
+   ../tbb_userguide/create_token_based_system
+   ../tbb_userguide/attach_flow_graph_to_arena

doc/main/tbb_userguide/attach_flow_graph_to_arena.rst

@@ -0,0 +1,46 @@
+.. _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 or restricting part of
+computation units. In some cases, you may want to use mechanisms within a flow graph.
+
+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
+

doc/main/tbb_userguide/snippets/flow_graph_examples.cpp

@@ -0,0 +1,76 @@
+/*
+    Copyright (c) 2005-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 <oneapi/tbb/flow_graph.h>
+#include <vector>
+
+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<tbb::core_type_id> 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<tbb::core_type_id> 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;
+}