Update from GitHub Actions

_sources/GSG/get_started.rst

@@ -0,0 +1,24 @@
+.. _Get_Started_Guide:
+
+Get Started with |full_name|
+=============================
+
+|short_name| Get Started Guide provides the information you need to begin working with oneTBB. 
+It is helpful for new users of parallel programming and experienced developers that want to improve code performance. 
+
+It is recommended for you to have a basic knowledge of C++ programming and some experience with parallel programming concepts. 
+
+
+To start using oneTBB, follow the next steps:
+*********************************************
+
+#. Learn what :ref:`oneTBB is<intro>` and see the :ref:`System Requirements<system_requirements>`. 
+#. :ref:`Install oneTBB<installation>`.
+#. Run your program using oneTBB following the :ref:`Next Steps <next_steps>`. 
+#. Learn how to :ref:`Integrate oneTBB into your project <integrate>` using CMake* and pkg-config tool. 
+#. See :ref:`oneTBB Samples <samples>`. 
+
+
+
+
+

_sources/GSG/installation.rst

@@ -0,0 +1,7 @@
+.. _installation:
+
+Installation
+============
+
+See the `installation instructions <https://github.com/oneapi-src/oneTBB/blob/master/INSTALL.md>`_ 
+that will help you to install |short_name| successfully.  

_sources/GSG/integrate.rst

@@ -0,0 +1,68 @@
+.. _integrate:
+
+Integrate oneTBB
+================
+
+If you want to improve the performance and scalability of your application, you can integrate oneTBB into your project. 
+For example, you may want to integrate oneTBB if your application needs to process large amounts of data in parallel. 
+
+To integrate oneTBB, you need to:
+
+* Link oneTBB with the project's source code. 
+* Provide the necessary compiler and linker flags.
+
+However, you can use CMake* and the pkg-config tool to simplify the process of integrating oneTBB into your project and handling its dependencies.
+See the instructions below to learn how to use the tools. 
+
+CMake*
+*******
+
+CMake* is a cross-platform build tool that helps you manage dependencies and build systems. 
+Integrating oneTBB into your project using CMake*:
+
+* Simplifies the process of building and linking against the library.
+* Ensures that your project can be built and run on multiple platforms.
+* Lets you manage oneTBB dependencies.
+
+To add oneTBB to another project using CMake*, add the following commands to your ``CMakeLists.txt`` file:
+
+.. code-block::
+
+       `find_package(TBB REQUIRED)`
+       `target_link_libraries(my_executable TBB::tbb)`
+
+After that, configure your project with CMake* as usual.
+
+
+Compile a Program Using pkg-config
+***********************************
+
+The pkg-config tool is used to simplify the compilation line by retrieving information about packages
+from special metadata files. It helps avoid large hard-coded paths and makes compilation more portable.
+
+To compile a test program ``test.cpp`` with oneTBB on Linux* OS, 
+provide the full path to search for included files and libraries, or provide a line as the following: 
+
+.. code-block::
+   
+       g++ -o test test.cpp $(pkg-config --libs --cflags tbb)
+
+Where:
+
+``--cflags`` provides oneTBB library include path:
+
+.. code-block::
+
+       $ pkg-config --cflags tbb
+       -I<path-to>/tbb/latest/lib/pkgconfig/../..//include
+
+``--libs`` provides the Intel(R) oneTBB library name and the search path to find it:
+
+.. code-block::
+   
+       $ pkg-config –libs tbb
+       -L<path to>tbb/latest/lib/pkgconfig/../..//lib/intel64/gcc4.8 -ltbb
+
+.. note::
+
+   For Windows* OS, additionally, use the ``--msvc-syntax`` option flag that converts the compiling and linking flags in an appropriate mode.

_sources/GSG/intro.rst

@@ -0,0 +1,29 @@
+.. _intro:
+
+What oneTBB Is 
+==============
+
+|full_name| is a runtime-based parallel programming model for C++ code that uses threads.
+The template-based runtime library can help you harness the latent performance of multi-core processors.
+
+oneTBB enables you to simplify parallel programming by breaking computation into parallel running tasks. Within a single process, 
+parallelism is carried out through threads, an operating system mechanism that allows the same or different sets of instructions 
+to be executed simultaneously. Using threads can make your program work faster and more efficiently.
+
+Here you can see one of the possible executions of tasks by threads.
+
+.. figure:: Images/how-oneTBB-works.png
+   :scale: 70%
+   :align: center
+
+Use oneTBB to write scalable applications that:
+
+* Specify logical parallel structure instead of threads.
+* Emphasize data-parallel programming.
+* Take advantage of concurrent collections and parallel algorithms.
+
+oneTBB supports nested parallelism and load balancing. It means that you can use the library without worrying about oversubscribing a system, which happens when more tasks are assigned to a system than it can handle efficiently. 
+
+oneTBB is used in different areas, such as scientific simulations, gaming, data analysis, etc. 
+
+It is available as a stand-alone product and as part of the |base_tk|.

_sources/GSG/next_steps.rst

@@ -0,0 +1,157 @@
+.. _next_steps:
+
+Next Steps
+===========
+
+After installing oneTBB, complete the following steps to start working with the library.
+
+Set the Environment Variables
+*****************************
+
+After installing |short_name|, set the environment variables:
+
+#. Go to the oneTBB installation directory. 
+
+#. Set the environment variables using the script in ``<install_dir>`` by running:
+
+   * On Linux* OS: ``vars.{sh|csh} in <install_dir>/tbb/latest/env``
+   * On Windows* OS: ``vars.bat in <install_dir>/tbb/latest/env``
+
+.. tip::
+
+   oneTBB can coordinate with Intel(R) OpenMP on CPU resources usage 
+   to avoid excessive oversubscription when both runtimes are used within a process.
+   To enable this feature set up ``TCM_ENABLE`` environment variable to ``1``.
+
+
+Build and Run a Sample 
+**********************
+
+.. tabs::
+
+   .. group-tab:: Windows* OS
+
+      #. Create a new C++ project using your IDE. In this example, Microsoft* Visual Studio* Code is used. 
+      #. Create an ``example.cpp`` file in the project. 
+      #. Copy and paste the code below. It is a typical example of a |short_name| algorithm. The sample calculates a sum of all integer numbers from 1 to 100. 
+
+         .. code:: 
+
+            #include <oneapi/tbb.h>
+            
+            int main (){
+                int sum = oneapi::tbb::parallel_reduce(
+                    oneapi::tbb::blocked_range<int>(1,101), 0,
+                    [](oneapi::tbb::blocked_range<int> const& r, int init) -> int {
+                        for (int v = r.begin(); v != r.end(); v++) {
+                            init += v;
+                        }
+                        return init;
+                    },
+                    [](int lhs, int rhs) -> int {
+                        return lhs + rhs;
+                    }
+                );
+      
+                printf("Sum: %d\n", sum);
+                return 0;
+            }
+      
+      #. Open the ``tasks.json`` file in the ``.vscode`` directory and paste the following lines to the args array:
+
+         * ``-Ipath/to/oneTBB/include`` to add oneTBB include directory. 
+         * ``path/to/oneTBB/`` to add oneTBB. 
+
+         For example:
+
+         .. code-block::
+
+                { 
+                   "tasks": [
+                        {
+                           "label": "build & run",
+                           "type": "cppbuild",
+                           "group": {
+                           "args": [ 
+                               "/IC:\\Program Files (x86)\\Intel\\oneAPI\\tbb\\2021.9.0\\include",
+                               "C:\\Program Files (x86)\\Intel\\oneAPI\\tbb\\2021.9.0\\lib\\ia32\\vc14\\tbb12.lib"
+                           
+
+      #. Build the project. 
+      #. Run the example. 
+      #. If oneTBB is configured correctly, the output displays ``Sum: 5050``.  
+
+   .. group-tab:: Linux* OS
+
+      #. Create an ``example.cpp`` file in the project. 
+      #. Copy and paste the code below. It is a typical example of a |short_name| algorithm. The sample calculates a sum of all integer numbers from 1 to 100. 
+
+         .. code:: 
+
+            #include <oneapi/tbb.h>
+
+            int main(){
+                int sum = oneapi::tbb::parallel_reduce(
+                    oneapi::tbb::blocked_range<int>(1,101), 0,
+                    [](oneapi::tbb::blocked_range<int> const& r, int init) -> int {
+                        for (int v = r.begin(); v != r.end(); v++) {
+                            init += v;
+                        }
+                        return init;
+                    },
+                    [](int lhs, int rhs) -> int {
+                        return lhs + rhs;
+                    }
+                );
+      
+                printf("Sum: %d\n", sum);
+                return 0;
+            }
+
+      #. Compile the code using oneTBB. For example, 
+
+         .. code-block:: 
+
+                g++ -std=c++11 example.cpp -o example -ltbb
+
+      
+      #. Run the executable:
+
+         .. code-block:: 
+
+                ./example
+      
+      #. If oneTBB is configured correctly, the output displays ``Sum: 5050``.  
+
+
+Hybrid CPU and NUMA Support
+****************************
+
+If you need NUMA/Hybrid CPU support in oneTBB, you need to make sure that HWLOC* is installed on your system.
+
+HWLOC* (Hardware Locality) is a library that provides a portable abstraction of the hierarchical topology of modern architectures (NUMA, hybrid CPU systems, etc). oneTBB relies on HWLOC* to identify the underlying topology of the system to optimize thread scheduling and memory allocation.
+
+Without HWLOC*, oneTBB may not take advantage of NUMA/Hybrid CPU support. Therefore, it's important to make sure that HWLOC* is installed before using oneTBB on such systems.
+
+Check HWLOC* on the System
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To check if HWLOC* is already installed on your system, run ``hwloc-ls``:
+
+* For Linux* OS, in the command line.
+* For Windows* OS, in the command prompt.
+
+If HWLOC* is installed, the command displays information about the hardware topology of your system. If it is not installed, you receive an error message saying that the command ``hwloc-ls`` could not be found.
+
+.. note:: For Hybrid CPU support, make sure that HWLOC* is version 2.5 or higher. For NUMA support, install HWLOC* version 1.11 or higher.
+
+Install HWLOC*
+^^^^^^^^^^^^^^
+
+To install HWLOC*, visit the official Portable Hardware Locality website (https://www-lb.open-mpi.org/projects/hwloc/).
+
+* For Windows* OS, binaries are available for download.
+* For Linux* OS, only the source code is provided and binaries should be built.
+
+On Linux* OS, HWLOC* can be also installed with package managers, such as APT*, YUM*, etc. To do so, run: sudo apt install hwloc.
+
+.. note:: For Hybrid CPU support, make sure that HWLOC* is version 2.5 or higher. For NUMA support, install HWLOC* version 1.11 or higher.

_sources/GSG/samples.rst

@@ -0,0 +1,49 @@
+.. _samples:
+
+oneTBB Samples
+==============
+
+To become an expert in using oneTBB, explore its samples and examples to learn how 
+to properly utilize the features and functionality of oneTBB and avoid common mistakes that may impede your performance.
+
+The following samples are available:
+
+* **Containers** 
+
+  * `concurrent_hash_map <https://github.com/oneapi-src/oneTBB/tree/master/examples/concurrent_hash_map>`_ 
+  * `concurrent_priority_queue <https://github.com/oneapi-src/oneTBB/tree/master/examples/concurrent_priority_queue>`_ 
+
+* `Flow Graph <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph>`_ 
+   * `A solution to the binpacking problem using a queue_node, a buffer_node, and function_node. <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/binpack>`_ 
+   * `Cholesky Factorization algorithm <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/cholesky>`_
+   * `An implementation of dining philosophers in graph using the reserving join_node <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/dining_philosophers>`_
+   * `A parallel implementation of bzip2 block-sorting file compressor <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/fgbzip2>`_
+   * `An example of a collection of digital logic gates that can be easily composed into larger circuits <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/logic_sim>`_
+   * `An example of a Kohonen Self-Organizing Map using cancellation <https://github.com/oneapi-src/oneTBB/tree/master/examples/graph/som>`_
+   * `Split computational kernel for execution between CPU and GPU <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-async-sycl>`_
+
+* **Algorithms**
+
+  * `parallel_for <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for>`_
+     * `Game of life overlay <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/game_of_life>`_
+     * `Polygon overlay <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/polygon_overlay>`_
+     * `Parallel seismic wave simulation <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/seismic>`_
+     * `Parallel 2-D raytracer/renderer <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for/tachyon>`_
+     * `Find largest matching substrings <https://github.com/oneapi-src/oneTBB/tree/master/examples/getting_started>`_
+     * `Resumable task: Split computational kernel for execution between CPU and GPU <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-resumable-tasks-sycl>`_
+  * `parallel_for_each <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_for_each>`_
+  * `parallel_pipeline <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_pipeline>`_
+  * `parallel_reduce <https://github.com/oneapi-src/oneTBB/tree/master/examples/parallel_reduce>`_
+
+* **Task Scheduler**
+
+  * `task_arena <https://github.com/oneapi-src/oneTBB/tree/master/examples/task_arena>`_
+  * `task_group <https://github.com/oneapi-src/oneTBB/tree/master/examples/task_group>`_
+  * `Execute similar computational kernels, with one task executing the SYCL* code and the other task executing the oneTBB code <https://github.com/oneapi-src/oneAPI-samples/tree/master/Libraries/oneTBB/tbb-task-sycl>`_
+
+* **Other**
+
+  * `Compute Fibonacci numbers in different ways <https://github.com/oneapi-src/oneTBB/tree/master/examples/test_all>`_
+
+
+.. note:: You can also refer to the `oneAPI Samples <https://oneapi-src.github.io/oneAPI-samples/>`_ to learn more about the ecosystem. 

_sources/GSG/system_requirements.rst

@@ -0,0 +1,6 @@
+.. _System_Requirements:
+
+System Requirements
+*******************
+
+Refer to the `oneTBB System Requirements <https://github.com/oneapi-src/oneTBB/blob/master/SYSTEM_REQUIREMENTS.md>`_.

_sources/index.rst

@@ -0,0 +1,15 @@
+|full_name|
+===========
+
+.. include:: index/index_intro.rst
+
+
+The following are some important topics for the ``novice user``:
+
+* :ref:`Get_Started_Guide` gives you a brief explanation of what oneTBB is. 
+* :ref:`Benefits` describes how |short_name| differs from typical threading packages.
+* :ref:`Package_Contents` describes dynamic library files and header files for Windows*, Linux*, and macOS* operating systems used in |short_name|.
+
+.. include:: index/useful_topics.rst
+
+.. include:: index/toctree.rst

_sources/index/index_intro.rst

@@ -0,0 +1,5 @@
+.. _index_intro:
+
+This document contains information about |short_name|. 
+It is a flexible performance library that let you break computation into parallel running tasks. 
+