Add CI workflow for testing documentation examples

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2021-2024 Intel Corporation
+# Copyright (c) 2021-2025 Intel Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -366,3 +366,53 @@ jobs:
             -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} -DCMAKE_CXX_COMPILER=${{ matrix.cxx_compiler }} `
             -DCMAKE_C_COMPILER=${{ matrix.c_compiler }} -DTBB_CPF=${{ matrix.preview }} -DTBB_TEST=OFF -DTBB_EXAMPLES=ON ..
           cmake --build . -v --target light_test_examples
+
+  linux-doc-examples-testing:
+    name: doc_examples_${{ matrix.os }}_${{ matrix.cxx_compiler }}_cxx${{ matrix.std }}_${{ matrix.build_type }}
+    runs-on: ['${{ matrix.os }}']
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            c_compiler: gcc
+            cxx_compiler: g++
+            std: 20
+            build_type: relwithdebinfo
+    steps:
+      - uses: actions/checkout@v4
+      - name: Test doc examples
+        run: |
+          mkdir build && cd build
+          cmake -DCMAKE_CXX_STANDARD=${{ matrix.std }} -DCMAKE_BUILD_TYPE=${{ matrix.build_type}} \
+            -DCMAKE_CXX_COMPILER=${{ matrix.cxx_compiler }} -DCMAKE_C_COMPILER=${{ matrix.c_compiler }} \
+            -DTBB_TEST=OFF -DTBB_DOC_EXAMPLES=ON ..
+          cmake --build . -v --parallel --target build-doc-examples
+          ctest -C ${{ matrix.build_type }} --timeout ${env:TEST_TIMEOUT} --output-on-failure -L doc-examples
+
+  windows-doc-examples-testing:
+    name: doc_examples_${{ matrix.os }}_${{ matrix.cxx_compiler }}_cxx${{ matrix.std }}_${{ matrix.build_type }}
+    runs-on: ['${{ matrix.os }}']
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-2022
+            generator: "Visual Studio 17 2022"
+            c_compiler: cl
+            cxx_compiler: cl
+            std: 20
+            build_type: relwithdebinfo
+    steps:
+      - uses: actions/checkout@v4
+      - name: Test doc examples
+        run: |
+          mkdir build
+          cd build
+          cmake -G "${{ matrix.generator }}" -A x64 -DCMAKE_CXX_STANDARD=${{ matrix.std }} `
+            -DCMAKE_BUILD_TYPE=${{ matrix.build_type}} -DCMAKE_CXX_COMPILER=${{ matrix.cxx_compiler }} `
+            -DCMAKE_C_COMPILER=${{ matrix.c_compiler }} -DTBB_TEST=OFF -DTBB_DOC_EXAMPLES=ON ..
+          cmake --build . --config ${{ matrix.build_type }} -v --parallel --target build-doc-examples
+          ctest -C ${{ matrix.build_type }} --timeout ${env:TEST_TIMEOUT} --output-on-failure -L doc-examples

CMakeLists.txt

@@ -330,6 +330,18 @@ if (TBB_EXAMPLES)
     add_subdirectory(examples)
 endif()
 
+
+if (TBB_DOC_EXAMPLES)
+    set(TBB_DOC_EXAMPLES_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/doc/main/examples_testing")
+    if (NOT EXISTS ${TBB_DOC_EXAMPLES_DIRECTORY})
+        message(FATAL_ERROR "Documentation examples are not found while testing was enabled")
+    else()
+        message(STATUS "Enabling testing for examples from documentation")
+        enable_testing()
+        add_subdirectory(${TBB_DOC_EXAMPLES_DIRECTORY})
+    endif()
+endif()
+
 if (TBB_BENCH)
     if (NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/benchmark)
         message(FATAL_ERROR "Benchmarks are not supported yet")

doc/main/examples_testing/CMakeLists.txt

@@ -0,0 +1,41 @@
+# Copyright (c) 2025 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+cmake_minimum_required(VERSION 3.11)
+project(doc_examples_testing LANGUAGES CXX)
+
+set(_reference_examples_path "${CMAKE_CURRENT_SOURCE_DIR}/../reference/examples")
+set(_userguide_examples_path "${CMAKE_CURRENT_SOURCE_DIR}/../tbb_userguide/examples")
+
+add_custom_target(build-doc-examples
+    COMMENT "Build oneTBB documentation samples")
+set(doc_examples_test_label "doc-examples")
+
+macro(add_doc_example _doc_example_path)
+    get_filename_component(_doc_example_name "${_doc_example_path}" NAME_WE)
+    add_executable(${_doc_example_name} EXCLUDE_FROM_ALL "${_doc_example_path}")
+
+    add_dependencies(${_doc_example_name} TBB::tbb TBB::tbbmalloc TBB::tbbmalloc_proxy)
+    target_link_libraries(${_doc_example_name} TBB::tbb TBB::tbbmalloc TBB::tbbmalloc_proxy)
+
+    add_dependencies(build-doc-examples ${_doc_example_name})
+    add_test(NAME ${_doc_example_name} COMMAND ${_doc_example_name})
+    set_tests_properties(${_doc_example_name} PROPERTIES LABELS "${doc_examples_test_label}")
+endmacro()
+
+file(GLOB_RECURSE DOC_EXAMPLES_LIST "${_reference_examples_path}/*.cpp" "${_userguide_examples_path}/*.cpp")
+
+foreach(_doc_example_path IN LISTS DOC_EXAMPLES_LIST)
+    add_doc_example(${_doc_example_path})
+endforeach()

doc/main/reference/custom_mutex_chmap.rst

@@ -67,92 +67,7 @@ and ``oneapi::tbb::rw_mutex`` meet the requirements above.
 The example below demonstrates how to wrap ``std::shared_mutex`` (C++17) to meet the requirements
 of `ReaderWriterMutex` and how to customize ``concurrent_hash_map`` to use this mutex.
 
-.. code:: cpp
-
-    #define TBB_PREVIEW_CONCURRENT_HASH_MAP_EXTENSIONS 1
-    #include "oneapi/tbb/concurrent_hash_map.h"
-    #include <shared_mutex>
-
-    class SharedMutexWrapper {
-    public:
-        // ReaderWriterMutex requirements
-
-        static constexpr bool is_rw_mutex = true;
-        static constexpr bool is_recursive_mutex = false;
-        static constexpr bool is_fair_mutex = false;
-
-        class scoped_lock {
-        public:
-            scoped_lock() : my_mutex_ptr(nullptr), my_writer_flag(false) {}
-            scoped_lock(SharedMutexWrapper& mutex, bool write = true)
-                : my_mutex_ptr(&mutex), my_writer_flag(write)
-            {
-                if (my_writer_flag) {
-                    my_mutex_ptr->my_mutex.lock();
-                } else {
-                    my_mutex_ptr->my_mutex.lock_shared();
-                }
-            }
-
-            ~scoped_lock() {
-                if (my_mutex_ptr) release();
-            }
-
-            void acquire(SharedMutexWrapper& mutex, bool write = true) {
-                if (my_mutex_ptr) release();
-
-                my_mutex_ptr = &mutex;
-                my_writer_flag = write;
-
-                if (my_writer_flag) {
-                    my_mutex_ptr->my_mutex.lock();
-                } else {
-                    my_mutex_ptr->my_mutex.lock_shared();
-                }
-            }
-
-            void release() {
-                if (my_writer_flag) {
-                    my_mutex_ptr->my_mutex.unlock();
-                } else {
-                    my_mutex_ptr->my_mutex.unlock_shared();
-                }
-            }
-
-            bool upgrade_to_writer() {
-                // std::shared_mutex does not have the upgrade/downgrade parallel_for_each_semantics
-                if (my_writer_flag) return true; // Already a writer
-
-                my_mutex_ptr->my_mutex.unlock_shared();
-                my_mutex_ptr->my_mutex.lock();
-                return false; // The lock was reacquired
-            }
-
-            bool downgrade_to_reader() {
-                if (!my_writer_flag) return true; // Already a reader
-
-                my_mutex_ptr->my_mutex.unlock();
-                my_mutex_ptr->my_mutex.lock_shared();
-                return false;
-            }
-
-            bool is_writer() const {
-                return my_writer_flag;
-            }
-
-        private:
-            SharedMutexWrapper* my_mutex_ptr;
-            bool                my_writer_flag;
-        };
-    private:
-        std::shared_mutex my_mutex;
-    }; // struct SharedMutexWrapper
-
-    int main() {
-        using map_type = oneapi::tbb::concurrent_hash_map<int, int,
-                                                          oneapi::tbb::tbb_hash_compare<int>,
-                                                          oneapi::tbb::tbb_allocator<std::pair<const int, int>>,
-                                                          SharedMutexWrapper>;
-
-        map_type map; // This object will use SharedMutexWrapper for thread safety of insert/find/erase operations
-    }
+.. literalinclude:: ./examples/custom_mutex_chmap_example.cpp
+    :language: c++
+    :start-after: /*begin_custom_mutex_chmap_example*/
+    :end-before: /*end_custom_mutex_chmap_example*/

doc/main/reference/examples/custom_mutex_chmap_example.cpp

@@ -0,0 +1,129 @@
+/*
+    Copyright (c) 2025 Intel Corporation
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+*/
+
+#if __cplusplus >= 201703L
+
+/*begin_custom_mutex_chmap_example*/
+#define TBB_PREVIEW_CONCURRENT_HASH_MAP_EXTENSIONS 1
+#include "oneapi/tbb/concurrent_hash_map.h"
+#include <shared_mutex>
+
+class SharedMutexWrapper {
+public:
+    // ReaderWriterMutex requirements
+
+    static constexpr bool is_rw_mutex = true;
+    static constexpr bool is_recursive_mutex = false;
+    static constexpr bool is_fair_mutex = false;
+
+    class scoped_lock {
+    public:
+        scoped_lock() : my_mutex_ptr(nullptr), my_writer_flag(false) {}
+        scoped_lock(SharedMutexWrapper& mutex, bool write = true)
+            : my_mutex_ptr(&mutex), my_writer_flag(write)
+        {
+            if (my_writer_flag) {
+                my_mutex_ptr->my_mutex.lock();
+            } else {
+                my_mutex_ptr->my_mutex.lock_shared();
+            }
+        }
+
+        ~scoped_lock() {
+            if (my_mutex_ptr) release();
+        }
+
+        void acquire(SharedMutexWrapper& mutex, bool write = true) {
+            if (my_mutex_ptr) release();
+
+            my_mutex_ptr = &mutex;
+            my_writer_flag = write;
+
+            if (my_writer_flag) {
+                my_mutex_ptr->my_mutex.lock();
+            } else {
+                my_mutex_ptr->my_mutex.lock_shared();
+            }
+        }
+
+        bool try_acquire(SharedMutexWrapper& mutex, bool write = true) {
+            if (my_mutex_ptr) release();
+
+            my_mutex_ptr = &mutex;
+
+            bool result = false;
+
+            if (my_writer_flag) {
+                result = my_mutex_ptr->my_mutex.try_lock();
+            } else {
+                result = my_mutex_ptr->my_mutex.try_lock_shared();
+            }
+
+            if (result) my_writer_flag = write;
+            return result;
+        }
+
+        void release() {
+            if (my_writer_flag) {
+                my_mutex_ptr->my_mutex.unlock();
+            } else {
+                my_mutex_ptr->my_mutex.unlock_shared();
+            }
+        }
+
+        bool upgrade_to_writer() {
+            // std::shared_mutex does not have the upgrade/downgrade semantics
+            if (my_writer_flag) return true; // Already a writer
+
+            my_mutex_ptr->my_mutex.unlock_shared();
+            my_mutex_ptr->my_mutex.lock();
+            return false; // The lock was reacquired
+        }
+
+        bool downgrade_to_reader() {
+            if (!my_writer_flag) return true; // Already a reader
+
+            my_mutex_ptr->my_mutex.unlock();
+            my_mutex_ptr->my_mutex.lock_shared();
+            return false;
+        }
+
+        bool is_writer() const {
+            return my_writer_flag;
+        }
+
+    private:
+        SharedMutexWrapper* my_mutex_ptr;
+        bool                my_writer_flag;
+    };
+private:
+    std::shared_mutex my_mutex;
+}; // struct SharedMutexWrapper
+
+int main() {
+    using map_type = oneapi::tbb::concurrent_hash_map<int, int,
+                                                      oneapi::tbb::tbb_hash_compare<int>,
+                                                      oneapi::tbb::tbb_allocator<std::pair<const int, int>>,
+                                                      SharedMutexWrapper>;
+
+    map_type map; // This object will use SharedMutexWrapper for thread safety of insert/find/erase operations
+}
+/*end_custom_mutex_chmap_example*/
+
+#else // C++17
+// Skip
+int main() {}
+#endif

doc/main/reference/examples/fixed_pool_example.cpp

@@ -0,0 +1,28 @@
+/*
+    Copyright (c) 2025 Intel Corporation
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+*/
+
+/*begin_fixed_pool_example*/
+#define TBB_PREVIEW_MEMORY_POOL 1
+#include "oneapi/tbb/memory_pool.h"
+
+int main() {
+    char buf[1024];
+    oneapi::tbb::fixed_pool my_pool(buf, 1024);
+
+    void* my_ptr = my_pool.malloc(10);
+    my_pool.free(my_ptr);
+}
+/*end_fixed_pool_example*/