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,36 @@ 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
+            job_name: linux_doc_examples_testing_ubuntu_latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build library
+        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 ..
+          cmake --build . -v --target tbb --target tbbmalloc --target tbbmalloc_proxy
+      - name: Test doc examples
+        run: |
+          source `find ./build -name vars.sh`
+          cd doc/main/examples_testing
+          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 }} ..
+          cmake --build . -v --target build-doc-examples
+          ctest -C ${{ matrix.build_type }} --timeout ${env:TEST_TIMEOUT} --output-on-failure

doc/main/examples_testing/CMakeLists.txt

@@ -0,0 +1,50 @@
+# 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)
+
+set(_tbb_include_path "${CMAKE_CURRENT_SOURCE_DIR}/../../../include")
+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")
+
+macro(add_example example_path)
+    message(STATUS "Adding ${_example_path}")
+
+    get_filename_component(_example_name "${_example_path}" NAME_WE)
+    add_executable(${_example_name} EXCLUDE_FROM_ALL "${_example_path}")
+
+    target_include_directories(${_example_name} PRIVATE ${_tbb_include_path})
+    target_link_libraries(${_example_name} tbb)
+    target_link_libraries(${_example_name} tbbmalloc)
+
+    add_dependencies(build-doc-examples ${_example_name})
+    add_test(NAME ${_example_name} COMMAND ${_example_name})
+endmacro()
+
+file(GLOB_RECURSE REFERENCE_EXAMPLES_LIST "${_reference_examples_path}/*.cpp")
+file(GLOB_RECURSE USERGUIDE_EXAMPLES_LIST "${_userguide_examples_path}/*.cpp")
+
+foreach(_example_path IN LISTS REFERENCE_EXAMPLES_LIST)
+    add_example(${_example_path})
+endforeach()
+
+foreach(_example_path IN LISTS USERGUIDE_EXAMPLES_LIST)
+    add_example(${_example_path})
+endforeach()
+
+enable_testing()

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*1024];
+    oneapi::tbb::fixed_pool my_pool(buf, 1024*1024);
+
+    void* my_ptr = my_pool.malloc(10);
+    my_pool.free(my_ptr);
+}
+/*end_fixed_pool_example*/