Add tasking documentation to user guide (#1791)

Co-authored-by: Aleksei Fedotov <[email protected]>
Co-authored-by: Alexey Kukanov <[email protected]>

Author: 3 people

doc/main/tbb_userguide/Cancellation_Without_An_Exception.rst

@@ -44,3 +44,29 @@ The example below shows how to use ``current_context()->cancel_group_execution()
        return 0;
    }
 
+task_group Cancellation Example
+===============================
+
+The interface to a ``task_group`` provides shortcuts to access its asoociated ``task_group_context``.
+The function ``oneapi::tbb::task_group::cancel()`` cancels the ``task_group_context`` associated
+with the ``task_group`` instance. And the free function
+``oneapi::tbb::is_current_task_group_canceling()`` returns ``true`` if the innermost ``task_group``
+executing on the calling thread is cancelling its tasks.
+
+Here is an example of how to use task cancellation with ``oneapi::tbb::task_group``. This code
+uses ``struct TreeNode`` and the function ``sequential_tree_search`` that are described in
+:ref:`creating_tasks_with_parallel_invoke`.
+
+The function ``parallel_tree_search_cancellable_impl`` cancels the ``task_group`` when a result
+is found.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_parallel_search_cancellation*/
+    :end-before: /*end_parallel_search_cancellation*/
+
+The call to ``tg.cancel()`` cancels the tasks in the ``task_group`` that have been submitted but
+have not started to execute. The task scheduler will not execute these tasks. Those tasks that
+have already started will not be interrupted but they can query the cancellation status of the
+``task_group`` by calling ``oneapi::tbb::is_current_task_group_canceling()`` and exit early if
+they detect cancellation.

doc/main/tbb_userguide/Images/concurrent_tasks.png

@@ -0,0 +1,17 @@
+.. _Parallelizing_with_Tasks:
+
+Parallelizing with Tasks
+========================
+
+When parallel loops or the flow graph are not sufficient, the |full_name|
+library supports parallelization directly with tasks. Tasks
+can be created using the function ``oneapi::tbb::parallel_invoke`` or
+the class ``oneapi::tbb::task_group``. 
+
+
+.. toctree::
+   :maxdepth: 4
+
+   ../tbb_userguide/creating_tasks_with_parallel_invoke
+   ../tbb_userguide/creating_tasks_with_task_group
+   ../tbb_userguide/task_group_thread_safety

doc/main/tbb_userguide/Images/concurrent_tasks_canceled.png

@@ -0,0 +1,55 @@
+.. _creating_tasks_with_parallel_invoke:
+
+Creating Tasks with parallel_invoke
+===================================
+
+Suppose you want to search a binary tree for the node that contains a specific value.
+Here is sequential code to do this:
+
+Nodes are represented by ``struct TreeNode``:
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_treenode*/
+    :end-before: /*end_treenode*/
+
+The function ``serial_tree_search`` is a recursive algorithm that checks the current node
+and, if the value is not found, calls itself on the left and right subtree. 
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_search_serial*/
+    :end-before: /*end_search_serial*/
+
+
+To improve performance, you can use ``oneapi::tbb::parallel_invoke`` to search the tree 
+in parallel:
+
+A recursive base case is used after a minimum size threshold is reached to avoid parallel overheads.
+Since more than one thread can call the base case concurrently as part of the same tree, ``result``
+is held in an atomic variable.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_sequential_tree_search*/
+    :end-before: /*end_sequential_tree_search*/
+
+The function ``oneapi::tbb::parallel_invoke`` runs multiple independent tasks in parallel.
+Here is a function ``parallel_invoke_search``, where two lambdas are passed that define tasks
+that search the left and right subtrees of the current node in parallel:
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_parallel_invoke_search*/
+    :end-before: /*end_parallel_invoke_search*/
+
+If the value is found, the pointer to the node that contains the value is stored
+in the ``std::atomic<TreeNode*> result``. This example uses recursion to create many tasks, instead of
+just two. The depth of the parallel recursion is limited by the ``depth_threshold`` parameter. After this depth is
+reached, the search falls back to a sequential approach. The value of ``result`` is periodically checked
+to see if the value has been found by other concurrent tasks, and if so, the search in the current task is
+terminated. Because multiple threads may access ``result`` concurrently, an atomic variable is used, even
+from the sequential base case.
+
+Because ``oneapi::tbb::parallel_invoke`` is a fork-join algorithm, each level of the recursion does not
+complete until both the left and right subtrees have completed.

doc/main/tbb_userguide/Parallelizing_with_Tasks.rst

@@ -0,0 +1,34 @@
+.. _creating_tasks_with_task_group:
+
+Creating Tasks with task_group
+==============================
+
+The |full_name| library supports parallelization directly with tasks. The class 
+``oneapi::tbb::task_group`` is used to run and wait for tasks in a less
+structured way than ``oneapi::tbb::parallel_invoke``. It is useful when you want to
+create a set of tasks that can be run in parallel, but you do not know how many there
+will be in advance.
+
+Here is code that uses ``oneapi::tbb::task_group`` to implement a parallel search in a
+binary tree. This code uses ``struct TreeNode`` and the function ``sequential_tree_search``
+that are described in :ref:`creating_tasks_with_parallel_invoke`.
+
+In ``parallel_tree_search_impl``, ``task_group::run`` is used to create new tasks for searching
+in the subtrees. The recursion does not wait on the ``task_group`` at each level.
+
+.. literalinclude:: ./examples/task_examples.cpp
+    :language: c++
+    :start-after: /*begin_parallel_search*/
+    :end-before: /*end_parallel_search*/
+
+This example uses recursion to create many tasks. The depth of the parallel recursion is
+limited by the ``depth_threshold`` parameter. After this depth is reached, no new tasks
+are created. The value of ``result`` is periodically checked to see if the value has been
+found by other concurrent tasks, and if so, the search in the current task is terminated.
+
+In this example, tasks that execute within the ``task_group tg`` create additional tasks
+by calling ``run`` on the same ``task_group`` object. These calls are thread-safe and the 
+call to ``tg.wait()`` will block until all of these tasks are complete. Although
+tasks might be added from different worker threads, these additions are logically nested
+within the top-most calls to ``tg.run``. There is therefore no race in adding these tasks from
+the worker threads and waiting for them in the main thread.