intel oneAPI Threading Building Blocks User Guide

: June 9, 2024
: Intel

Table of Contents

intel oneAPI Threading Building Blocks
Product Information
System Requirements
Installation
Usage Instructions
Get Started with one API Threading Building Blocks (one TB)
- Before You Begin
- Find more
Notices and Disclaimers
References
Read User Manual Online (PDF format)
Download This Manual (PDF format)

intel oneAPI Threading Building Blocks

intel-oneAPI-Threading-Building-Blocks-PRODUCT

Product Information

one API Threading Building Blocks (one TB)

oneAPI Threading Building Blocks (oneTBB) is a runtime-based parallel programming model for C++ code that uses threads. It is a template-based runtime library designed to help harness the latent performance of multi-core processors. oneTBB simplifies parallel programming by breaking computation into parallel running tasks. Parallelism is carried out within a single process through threads, an operating system mechanism that enables the same or different sets of instructions to be executed simultaneously.

oneTBB can be downloaded as a stand-alone product or as part of the Intel(R) oneAPI Base Toolkit. The product comes with a set of system requirements that should be met before installation.

System Requirements

Refer to the oneTBB System Requirements.

Installation

Download oneTBB as a stand-alone product or as a part of the Intel(R) oneAPI Base Toolkit.
Refer to the Installation Guide for a stand-alone version (Windows OS and Linux OS) and Intel(R) oneAPI Toolkits Installation Guide.

Usage Instructions

* After installing oneTBB, set the environment variables by going to the oneTBB installation directory. By default, the installation directory is as follows:

For Linux* OS: /opt/intel/Konami/tab/latest/env/vars.sh

For Windows* OS: %ProgramFiles(x86)%InteloneAPItbblatestenvvars.bat

* Compile a program using oneTBB on Linux* OS and macOS* using the pkg-config tool. Provide the full path to search for including files and libraries, or provide a simple line like this:

g++ -o test test.cpp $(pkg-config –libs –flags tab)

For Windows* OS, additionally use the –msvc-syntax option flag that converts the compiling and linking flags in an appropriate mode.
Refer to the Developer Guide and API Reference on GitHub for detailed notes, known issues, and changes.

Get Started with one API Threading Building Blocks (one TB)

oneAPI Threading Building Blocks (oneTBB) 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.

Use one tab 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. oneTBB is available as a stand-alone product and as part of the Intel® oneAPI Base Toolkit.

System Requirements

Refer to the oneTBB System Requirements.

Download Intel(R) oneAPI Threading Building Blocks (oneTBB)

Download oneTBB as a stand-alone product or as a part of the Intel(R) oneAPI Base Toolkit. See Installation Guide for a stand-alone version (Windows OS and Linux OS) and Intel(R) oneAPI Toolkits Installation Guide.

Before You Begin

After installing oneTBB, you need to set the environment variables:

Go to the oneTBB installation directory (). By default, is the following:
On Linux* OS:
For superusers (root): /opt/intel/Konami
For ordinary users (non-root): $HOME/intel/Konami
On Windows* OS:
\Intel\oneAPI
Set the environment variables, using the script in
, by running
- *On Linux OS:** vars.{sh|csh} in /tbb/latest/env
- *On Windows OS:** vars.bat in /tbb/latest/env

Example
Below you can find a typical example for a oneTBB algorithm. The sample calculates a sum of all integer numbers from 1 to 100.

oneAPI Threading Building Blocks (oneTBB) and pkg-config tool

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.

Compile a program using pkg-config

To compile a test program test.cpp with oneTBB on Linux OS and macOS, provide the full path to search for include files and libraries, or provide a simple line like this:

Where:

cflags provides oneTBB library including path:
libs provide the Intel(R) oneTBB library name and the search path to find it:
NOTE For Windows* OS, additionally use the –msvc-syntax option flag that converts the compiling and linking flags in an appropriate mode.

Find more

oneTBB Community Forum
Product FAQs
Support requests
Use these resources if you need support with oneTBB.
Release Notes Find up-to-date information about the product, including detailed notes, known issues, and changes.
Documentation: Developer Guide and API Reference
Learn to use oneTBB.
**GitHub*** Find oneTBB implementation in open source.

Notices and Disclaimers

Intel technologies may require enabled hardware, software or service activation.
No product or component can be absolutely secure.
Your costs and results may vary.
© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.
No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.
The products described may contain design defects or errors known as errata which ay cause the product to deviate from published specifications. Current characterized errata are available on request.
Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising fromcourse of performance, course of dealing, or usage in trade.

*Install oneTBB on Windows OS**

This section describes how you can deploy the oneAPI Threading Building Blocks (oneTBB) library on a Windows* OS machine.
If you plan to install oneTBB as a part of Intel® oneAPI Base Toolkit, refer to the corresponding section of the Intel(R) oneAPI Toolkits Installation Guide.
If you plan to install oneTBB as a standalone product, follow the instructions below, using the installer GUI or a package manager of your choice.
Learn how to install oneTBB with GUI and package manager: Install with GUI Install with a Package Manager

Install with GUI

Step 1. Select the preferred installer

Go to the Download page. A list of available installers is displayed.
Decide on the Windows installer type that you will use:
- Online installer has a smaller file size but requires a permanent Internet connection while running.
- Offline installer has a bigger file size but requires an Internet connection only to download the installer file, and then runs offline.
Having decided on the installer type, click the corresponding link to start the download.
Wait for the download to complete.

Step 2. Prepare the installer

For offline installers:

Run the .exe file you have downloaded. The installation package extractor will be launched.
Specify the path where to extract the package – default is C:\Users\\Downloads\w_tbb_oneapip_offline.
If necessary, select the Remove temporary extracted files after installation checkbox.
Click Extract.
For the online installer, the download starts automatically after you run the .exe file.

Step 3. Run the setup

If you are running the offline installer, click Continue to proceed. The online installer will proceed automatically.
In the Summary step, select the I accept the terms of the license agreement checkbox.
Select the installation mode:

To use default installation settings, select Recommended Installation. oneTBB will be installed in the default location: %Program FIles (x86)%\Intel\oneAPI\. Click Continue and proceed to the Integrate IDE step.
To modify installation settings, select Custom Installation and click Customize. You will proceed to the Select Components step. However, no components other than oneTBB can be selected due to solution nature. In this mode, you can change the default installation location by clicking Change in the bottom-left corner of the window.

At the Integrate IDE step, the program checks if it is possible to deploy oneTBB fully integrated with Microsoft Visual Studio IDE – for that, the supported IDE version must be installed on the target machine. If not installed, you can exit the setup and restart it after installing the IDE, or proceed without integration.
At the Software Improvement Program step, select the option you prefer. Then click Install to start the installation.
Wait for the process to complete. Then click Finish to close the installer or Go to Installed Products to check for updates or take other actions.

NOTE Remember to configure environment variables after installation. See the Before You Begin section to learn about it.

Install with a Package Manager

To install oneTBB with a package manager, run the corresponding command described in the documentation:
Conda
Pip
NuGet
NOTE Remember to configure environment variables after installation. See Before You Begin section to learn about it.

Upgrading oneTBB

The seamless upgrade is supported for oneTBB 2021.1 and later versions. To upgrade oneTBB to the latest version, run the setup, as described above.
If you used to work with older versions (TBB), consider that the new versions of oneTBB do not provide backward compatibility. See TBB Revamp: Background, Changes, and Modernization for details. Also, refer to
Migrating from TBB for more information on migrating to oneTBB.

Uninstalling oneTBB

To uninstall oneTBB, use Applications and Features or Programs and Features.

*Install oneTBB on Linux OS**

This section describes how you can deploy the oneAPI Threading Building Blocks (oneTBB) library on a Linux* machine. Choose the preferred way:
Install oneTBB Using Command Line
Install oneTBB Using Package Managers of choice:
Conda
APT
YUM
PIP
NuGet
NOTE You can also install one TB on a Linux* OS machine using GUI. See Intel(R) oneAPI Installation Guide to learn more.

Install oneTBB Using Command Line

To install oneTBB, run one of the following commands according to your role:
root:
user:

Where:

silent – Run the installer in non-interactive (silent) mode.
eula – Accept or decline End User License Agreement (EULA), supported values: accept or decline (default).
components – Let you custom installed components.

For example:

Install oneTBB Using Package Managers

Follow the instructions, using a package manager of your choice.

Conda

This section provides general instructions on installing the oneAPI Threading Building Blocks (oneTBB) via the
Conda* package manager. For additional installation notes, refer to the Conda documentation.
To install oneTBB, run the following command:
You can also use: conda install -c intel/label/intel tbb-devel
NOTE See Intel(R) oneAPI Installation Guide to learn how to configure Conda.

APT

To install oneTBB using APT*, run:
For example:

NOTE See Intel(R) oneAPI Installation Guide to learn how to configure YUM.

To install oneTBB using PIP*, run:

For example:

NuGet

To install oneTBB from NuGet* using the command line, do the following:

Go to nuget.org
Run:

NOTE See Intel(R) oneAPI Installation Guide to learn how to configure NuGet*.
NOTE Remember to configure environment variables after installation. See the Before You Begin section to learn about it.

Upgrading oneTBB

The seamless upgrade is supported for oneTBB 2021.1 and later versions. To upgrade oneTBB to the latest version, run the setup, as described above.
If you used to work with older versions (TBB), consider that the new versions of oneTBB do not provide backward compatibility. See TBB Revamp: Background, Changes, and Modernization for details. Also, refer to Migrating from TBB for more information on migrating to one TB.