C++20 Modules Support

Note

Support for C++20 modules is experimental and subject to change in future releases.

oneTBB provides a C++20 module interface unit, tbb.cppm, that lets you use oneTBB via import tbb; instead of regular library headers. The module is installed as a source file under <install-prefix>/include/oneapi/tbb.cppm and must be compiled as part of your own build target.

CMake* Integration

To add the tbb module to your CMake* target, locate tbb.cppm using the INTERFACE_INCLUDE_DIRECTORIES property of the TBB::tbb target and register it as a CXX_MODULES file set:

Note

To support C++20 modules, CMake* 3.28 or later and a compiler and generator with C++20 modules support are required. Refer to the CMake* documentation for the list of supported compilers and generators.

cmake_minimum_required(VERSION 3.28)
project(myapp CXX)

set(CMAKE_CXX_STANDARD 20)

find_package(TBB REQUIRED)

add_executable(my_executable main.cpp)
target_link_libraries(my_executable PRIVATE TBB::tbb)

get_target_property(_tbb_include_dir TBB::tbb INTERFACE_INCLUDE_DIRECTORIES)
target_sources(my_executable PRIVATE
    FILE_SET cxx_modules TYPE CXX_MODULES
    BASE_DIRS ${_tbb_include_dir}
    FILES ${_tbb_include_dir}/oneapi/tbb.cppm
)

An then in your C++ source files, you can import the module:

import tbb;
int main() {
    tbb::parallel_for(0, 100, [](int i) { /* ... */ });
}

Note

Translation units that use import tbb; are ABI-compatible with those that use library headers.

Enabling Preview Features

oneTBB preview features are gated by TBB_PREVIEW_* macros that are normally defined before including TBB headers. With modules, macros defined by the consumer before import tbb; cannot affect the module’s already-compiled interface.

To enable a preview feature, define the corresponding macro when compiling tbb.cppm itself. In CMake*, use target_compile_definitions:

find_package(TBB REQUIRED)

add_executable(my_executable main.cpp)
target_link_libraries(my_executable PRIVATE TBB::tbb)

get_target_property(_tbb_include_dir TBB::tbb INTERFACE_INCLUDE_DIRECTORIES)
target_sources(my_executable PRIVATE
    FILE_SET cxx_modules TYPE CXX_MODULES
    BASE_DIRS ${_tbb_include_dir}
    FILES ${_tbb_include_dir}/oneapi/tbb.cppm
)

# Enable preview feature X when compiling the target that uses the module
target_compile_definitions(my_executable PRIVATE TBB_PREVIEW_FEATURE_X=1)

After this, the preview API is included in the compiled module and available to all translation units that use import tbb;.

Usage Of Predefined Macros

C++20 modules do not export preprocessor macros. Macros defined in oneTBB library headers (such as version or feature-test macros) are not available after import tbb;.

As a workaround, include the <oneapi/tbb/version.h> header alongside the module import.

Caution

In typical usage with CMake* integration, tbb.cppm is compiled as part of your target, so TBB_PREVIEW_* macros defined via target_compile_definitions are already applied when the module is built. There is no need to redefine them in application source files. In any other scenario, make sure to define the same preview macros both when compiling the module and in your source code to avoid a mismatch.

// It is assumed that the application is compiled with preview macros predefined
#include <oneapi/tbb/version.h>  // macros available here
import tbb;

static_assert(TBB_VERSION_MAJOR >= 2023, "Major version 2023 or later is required");

// Feature-test macros are also available
#ifdef TBB_HAS_FEATURE_X
// use feature X
#endif