Document a way to flow graph can be attached to arbitrary task_arena (u…

…xlfoundation#785)

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

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.

Signed-off-by: Serov, Vladimir <vladimir.serov@intel.com>
Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>
Co-authored-by: Alexandra Epanchinzeva <alexandra.epanchinzeva@intel.com>

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,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
+

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 <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;
+}