Update Get Started Guide (#1110)
This commit is contained in:
Alexandra authored and GitHub committed
1 parent
3c162e4ed6
commit
95f951176a
15 files changed
+254
-131
No files matched your search
@@ -1,48 +0,0 @@
|
||||
.. _Before_You_Begin:
|
||||
|
||||
Before You Begin
|
||||
****************
|
||||
|
||||
After installing |short_name|, you need to set the environment variables:
|
||||
|
||||
#. Go to the oneTBB installation directory (``<install_dir>``). By default, ``<install_dir>`` is the following:
|
||||
|
||||
* On Linux* OS:
|
||||
|
||||
* For superusers (root): ``/opt/intel/oneapi``
|
||||
* For ordinary users (non-root): ``$HOME/intel/oneapi``
|
||||
|
||||
* On Windows* OS:
|
||||
|
||||
* ``<Program Files>\Intel\oneAPI``
|
||||
|
||||
#. 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``
|
||||
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
Below you can find a typical example for a |short_name| algorithm.
|
||||
The sample calculates a sum of all integer numbers from 1 to 100.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
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;
|
||||
}
|
||||
);
|
||||
+16
-9
@@ -1,17 +1,24 @@
|
||||
.. _Get_Started_Guide:
|
||||
|
||||
Get Started with |short_name|
|
||||
==============================
|
||||
Get Started with |full_name|
|
||||
=============================
|
||||
|
||||
.. include:: intro_gsg.rst
|
||||
|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.
|
||||
|
||||
.. include:: system_requirements.rst
|
||||
It is recommended for you to have a basic knowledge of C++ programming and some experience with parallel programming concepts.
|
||||
|
||||
.. include:: before_beginning_and_example.rst
|
||||
|
||||
.. include:: hybrid_cpu_support.rst
|
||||
To start using oneTBB, follow the next steps:
|
||||
*********************************************
|
||||
|
||||
Find more
|
||||
*********
|
||||
#. 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>`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
See our `documentation <https://oneapi-src.github.io/oneTBB/>`_ to learn more about |short_name|.
|
||||
@@ -1,40 +0,0 @@
|
||||
.. _hybrid_cpu_support:
|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
@@ -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|.
|
||||
@@ -1,23 +0,0 @@
|
||||
.. _Intro_gsg:
|
||||
|
||||
|
||||
|full_name| is a runtime-based parallel programming model for C++ code that uses threads.
|
||||
It consists of a template-based runtime library to 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.
|
||||
|
||||
Here you can see one of the possible executions of tasks by threads.
|
||||
|
||||
.. figure:: /GSG/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 being worried about oversubscribing a system.
|
||||
@@ -0,0 +1,120 @@
|
||||
.. _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``
|
||||
|
||||
|
||||
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``.
|
||||
|
||||
|
||||
@@ -1,9 +1,12 @@
|
||||
.. _examples:
|
||||
.. _samples:
|
||||
|
||||
oneTBB Samples
|
||||
==============
|
||||
|
||||
Refer to the following examples to see how |short_name| works.
|
||||
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**
|
||||
|
||||
@@ -43,3 +46,4 @@ Refer to the following examples to see how |short_name| works.
|
||||
* `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.
|
||||
+3
-2
@@ -56,7 +56,8 @@ extensions = [
|
||||
'sphinx.ext.imgmath',
|
||||
'sphinx.ext.ifconfig',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinx.ext.githubpages'
|
||||
'sphinx.ext.githubpages',
|
||||
'sphinx_tabs.tabs'
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
@@ -77,7 +78,7 @@ master_doc = 'index'
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
language = 'en'
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
|
||||
@@ -16,8 +16,12 @@
|
||||
:maxdepth: 2
|
||||
|
||||
/GSG/get_started
|
||||
/GSG/intro
|
||||
/GSG/system_requirements
|
||||
/GSG/installation
|
||||
/GSG/examples
|
||||
/GSG/next_steps
|
||||
/GSG/integrate
|
||||
/GSG/samples
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
@@ -86,4 +86,4 @@ As an optimization hint, ``F`` might return a ``task_handle``, which task object
|
||||
* `oneapi::tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_
|
||||
* `oneapi::tbb::task_group_context specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/task_group_context_cls.html>`_
|
||||
* `oneapi::tbb::task_group_status specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_status_enum.html>`_
|
||||
* :doc:`oneapi::tbb::task_handle class <task_group_extensions/task_handle>`
|
||||
* `oneapi::tbb::task_handle class <https://oneapi-src.github.io/oneAPI-spec/spec/elements/oneTBB/source/task_scheduler/task_group/task_handle.html>`_
|
||||
@@ -6,8 +6,8 @@ Flow Graph Tips and Tricks
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
../tbb_userguide/Flow_Graph_waiting_tips
|
||||
../tbb_userguide/Flow-Graph-waiting-tips
|
||||
../tbb_userguide/Flow_Graph_making_edges_tips
|
||||
../tbb_userguide/Flow_Graph_nested_parallelism_tips
|
||||
../tbb_userguide/Flow_Graph_resource_tips
|
||||
../tbb_userguide/Flow_Graph_exception_tips
|
||||
../tbb_userguide/Flow-Graph-exception-tips
|
||||
@@ -140,7 +140,8 @@ to set the stack size for oneTBB worker threads:
|
||||
|
||||
Terminating oneTBB scheduler
|
||||
---------------------------------------
|
||||
:ref:`task_scheduler_handle_reference`
|
||||
|
||||
`task_scheduler_handle <https://oneapi-src.github.io/oneAPI-spec/spec/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.html>`_
|
||||
allows waiting for oneTBB worker threads completion:
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
.. _attach_flow_graph_to_arena:
|
||||
|
||||
Attach Flow Graph to an Arbitrary Task Arena
|
||||
======================
|
||||
=============================================
|
||||
|
||||
|
||||
|short_name| ``task_arena`` interface provides mechanisms to guide tasks
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
.. _Lazy_Initialization:
|
||||
|
||||
Lazy Initialization
|
||||
==================
|
||||
====================
|
||||
|
||||
|
||||
.. container:: section
|
||||
|
||||
Reference in new issue
Block a user