Merge remote-tracking branch 'upstream/main' into task_group_extensions

# Conflicts:
#	source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst

Author: anton-potapov

source/elements/oneTBB/source/algorithms.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -15,6 +15,8 @@ Parallel Functions
 .. toctree::
    :titlesonly:
 
+   algorithms/functions/collaborative_call_once_func.rst
+
    algorithms/functions/parallel_for_func.rst
    algorithms/functions/parallel_reduce_func.rst
    algorithms/functions/parallel_deterministic_reduce_func.rst

source/elements/oneTBB/source/algorithms/blocked_ranges/blocked_range2d_cls.rst

@@ -17,39 +17,41 @@ A ``blocked_range2d`` meets the :doc:`Range requirements <../../named_requiremen
 
 .. code:: cpp
 
-    // Defined in header <tbb/blocked_range2d.h>
-
-    namespace tbb {
-
-        template<typename RowValue, typename ColValue=RowValue>
-        class blocked_range2d {
-        public:
-            // Types
-            using row_range_type = blocked_range<RowValue>;
-            using col_range_type = blocked_range<ColValue>;
-
-            // Constructors
-            blocked_range2d(
-                RowValue row_begin, RowValue row_end,
-                typename row_range_type::size_type row_grainsize,
-                ColValue col_begin, ColValue col_end,
-                typename col_range_type::size_type col_grainsize);
-            blocked_range2d( RowValue row_begin, RowValue row_end,
-                            ColValue col_begin, ColValue col_end );
-            // Splitting constructors
-            blocked_range2d( blocked_range2d& r, split );
-            blocked_range2d( blocked_range2d& r, proportional_split proportion );
-
-            // Capacity
-            bool empty() const;
-
-            // Access
-            bool is_divisible() const;
-            const row_range_type& rows() const;
-            const col_range_type& cols() const;
-        };
-
-    } // namespace tbb
+    // Defined in header <oneapi/tbb/blocked_range2d.h>
+    
+    namespace oneapi {
+        namespace tbb {
+
+            template<typename RowValue, typename ColValue=RowValue>
+            class blocked_range2d {
+            public:
+                // Types
+                using row_range_type = blocked_range<RowValue>;
+                using col_range_type = blocked_range<ColValue>;
+
+                // Constructors
+                blocked_range2d(
+                    RowValue row_begin, RowValue row_end,
+                    typename row_range_type::size_type row_grainsize,
+                    ColValue col_begin, ColValue col_end,
+                    typename col_range_type::size_type col_grainsize);
+                blocked_range2d( RowValue row_begin, RowValue row_end,
+                                ColValue col_begin, ColValue col_end );
+                // Splitting constructors
+                blocked_range2d( blocked_range2d& r, split );
+                blocked_range2d( blocked_range2d& r, proportional_split proportion );
+
+                // Capacity
+                bool empty() const;
+
+                // Access
+                bool is_divisible() const;
+                const row_range_type& rows() const;
+                const col_range_type& cols() const;
+            };
+
+        } // namespace tbb
+    } // namespace oneapi
 
 Requirements:
 

source/elements/oneTBB/source/algorithms/blocked_ranges/blocked_range3d_cls.rst

@@ -13,39 +13,42 @@ A ``blocked_range3d`` is the three-dimensional extension of ``blocked_range2d``.
 
 .. code:: cpp
 
-    namespace tbb {
-        template<typename PageValue, typename RowValue=PageValue, typename ColValue=RowValue>
-        class blocked_range3d {
-        public:
-            // Types
-            using page_range_type = blocked_range<PageValue>;
-            using row_range_type = blocked_range<RowValue>;
-            using col_range_type = blocked_range<ColValue>;
-
-            // Constructors
-            blocked_range3d(
-                PageValue page_begin, PageValue page_end,
-                typename page_range_type::size_type page_grainsize,
-                RowValue row_begin, RowValue row_end,
-                typename row_range_type::size_type row_grainsize,
-                ColValue col_begin, ColValue col_end,
-                typename col_range_type::size_type col_grainsize );
-            blocked_range3d( PageValue page_begin, PageValue page_end
-                            RowValue row_begin, RowValue row_end,
-                            ColValue col_begin, ColValue col_end );
-            blocked_range3d( blocked_range3d& r, split );
-            blocked_range3d( blocked_range3d& r, proportional_split& proportion );
-
-            // Capacity
-            bool empty() const;
-
-            // Access
-            bool is_divisible() const;
-            const page_range_type& pages() const;
-            const row_range_type& rows() const;
-            const col_range_type& cols() const;
-        };
-    }
+    namespace oneapi {
+        namespace tbb {
+            template<typename PageValue, typename RowValue=PageValue, typename ColValue=RowValue>
+            class blocked_range3d {
+            public:
+                // Types
+                using page_range_type = blocked_range<PageValue>;
+                using row_range_type = blocked_range<RowValue>;
+                using col_range_type = blocked_range<ColValue>;
+
+                // Constructors
+                blocked_range3d(
+                    PageValue page_begin, PageValue page_end,
+                    typename page_range_type::size_type page_grainsize,
+                    RowValue row_begin, RowValue row_end,
+                    typename row_range_type::size_type row_grainsize,
+                    ColValue col_begin, ColValue col_end,
+                    typename col_range_type::size_type col_grainsize );
+                blocked_range3d( PageValue page_begin, PageValue page_end
+                                RowValue row_begin, RowValue row_end,
+                                ColValue col_begin, ColValue col_end );
+                blocked_range3d( blocked_range3d& r, split );
+                blocked_range3d( blocked_range3d& r, proportional_split& proportion );
+
+                // Capacity
+                bool empty() const;
+
+                // Access
+                bool is_divisible() const;
+                const page_range_type& pages() const;
+                const row_range_type& rows() const;
+                const col_range_type& cols() const;
+            };
+
+        } // namespace tbb
+    } // namespace oneapi        
 
 Requirements:
 

source/elements/oneTBB/source/algorithms/blocked_ranges/blocked_range_cls.rst

@@ -21,35 +21,38 @@ to the loop templates ``parallel_for``, ``parallel_reduce``, or ``parallel_scan`
 
 .. code:: cpp
 
-    // Defined in header <tbb/blocked_range.h>
-
-    namespace tbb {
-
-        template<typename Value>
-        class blocked_range {
-        public:
-            // types
-            using size_type = size_t;
-            using const_iterator = Value;
-
-            // constructors
-            blocked_range( Value begin, Value end, size_type grainsize=1 );
-            blocked_range( blocked_range& r, split );
-            blocked_range( blocked_range& r, proportional_split& proportion );
-
-            // capacity
-            size_type size() const;
-            bool empty() const;
-
-            // access
-            size_type grainsize() const;
-            bool is_divisible() const;
-
-            // iterators
-            const_iterator begin() const;
-            const_iterator end() const;
-       };
-    }
+    // Defined in header <oneapi/tbb/blocked_range.h>
+    
+    namespace oneapi {
+        namespace tbb {
+
+            template<typename Value>
+            class blocked_range {
+            public:
+                // types
+                using size_type = size_t;
+                using const_iterator = Value;
+
+                // constructors
+                blocked_range( Value begin, Value end, size_type grainsize=1 );
+                blocked_range( blocked_range& r, split );
+                blocked_range( blocked_range& r, proportional_split& proportion );
+
+                // capacity
+                size_type size() const;
+                bool empty() const;
+
+                // access
+                size_type grainsize() const;
+                bool is_divisible() const;
+
+                // iterators
+                const_iterator begin() const;
+                const_iterator end() const;
+            };
+
+        } // namespace tbb
+    } // namespace oneapi
 
 Requirements:
 

source/elements/oneTBB/source/algorithms/examples/blocked_rangeNd_example.cpp

@@ -1,10 +1,10 @@
-#include "tbb/tbb_config.h"
+#include "oneapi/tbb/tbb_config.h"
 
 #if __TBB_CPP11_PRESENT && __TBB_CPP11_ARRAY_PRESENT && __TBB_CPP11_TEMPLATE_ALIASES_PRESENT
 #include "blocked_rangeNd_example.h"
 #endif
 
-#include "tbb/tbb_stddef.h"
+#include "oneapi/tbb/tbb_stddef.h"
 #include <vector>
 
 int main() {

source/elements/oneTBB/source/algorithms/examples/blocked_rangeNd_example.h

@@ -1,8 +1,8 @@
 #define TBB_PREVIEW_BLOCKED_RANGE_ND 1
-#include "tbb/blocked_rangeNd.h"
+#include "oneapi/tbb/blocked_rangeNd.h"
 
-#include "tbb/parallel_for.h"
-#include "tbb/parallel_reduce.h"
+#include "oneapi/tbb/parallel_for.h"
+#include "oneapi/tbb/parallel_reduce.h"
 
 template<typename Features>
 float kernel3d(const Features& feature_maps, int i, int j, int k,
@@ -21,9 +21,9 @@ template<typename Features, typename Output>
 void convolution3d(const Features& feature_maps, Output& out,
                    int out_length, int out_width, int out_heigth,
                    int kernel_length, int kernel_width, int kernel_height) {
-    using range_t = tbb::blocked_rangeNd<int, 3>;
+    using range_t = oneapi::tbb::blocked_rangeNd<int, 3>;
 
-    tbb::parallel_for(
+    oneapi::tbb::parallel_for(
         range_t({0, out_length}, {0, out_width}, {0, out_heigth}),
         [&](const range_t& out_range) {
             auto out_x = out_range.dim(0);

source/elements/oneTBB/source/algorithms/examples/range_concept.h

@@ -1,4 +1,4 @@
-#include <tbb/tbb_stddef.h> // for split tags
+#include <oneapi/tbb/tbb_stddef.h> // for split tags
 
 struct TrivialNaturalRange {
     // restore the default constructor
@@ -10,14 +10,14 @@ struct TrivialNaturalRange {
     bool is_divisible() const { return upper > lower + 1; }
 
     // basic splitting constructor
-    TrivialNaturalRange(TrivialNaturalRange& r, tbb::split) {
+    TrivialNaturalRange(TrivialNaturalRange& r, oneapi::tbb::split) {
         size_t m = r.lower + (r.upper - r.lower) / 2;
         upper = r.upper;
         r.upper = lower = m;
     }
 
     // optional proportional splitting constructor
-    TrivialNaturalRange(TrivialNaturalRange& r, tbb::proportional_split p) {
+    TrivialNaturalRange(TrivialNaturalRange& r, oneapi::tbb::proportional_split p) {
         size_t m = r.lower + ((r.upper - r.lower) * p.left()) / (p.left() + p.right());
         if (m == r.lower)
             m++;

source/elements/oneTBB/source/algorithms/functions/collaborative_call_once_func.rst

@@ -0,0 +1,86 @@
+.. SPDX-FileCopyrightText: 2021 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+=======================
+collaborative_call_once
+=======================
+**[algorithms.collaborative_call_once]**
+
+Function template that executes function exactly once.
+
+.. code:: cpp
+
+    // Defined in header <oneapi/tbb/collaborative_call_once.h>
+
+    namespace oneapi {
+        namespace tbb {
+
+            template<typename Func, typename... Args>
+            void collaborative_call_once(collaborative_once_flag& flag, Func&& func, Args&&... args);
+
+        } // namespace tbb
+    } // namespace oneapi
+
+Requirements:
+
+* ``Func`` type must meet the ``Function Objects``
+  requirements from the [function.objects] section of the ISO C++ Standard section.
+
+Executes the ``Func`` object only once, even if it is called concurrently. It allows other threads
+blocked on the same ``collaborative_once_flag`` to join oneTBB parallel construction called
+within the ``Func`` object.
+
+In case of the exception thrown from the ``Func`` object, the thread calling the ``Func`` object 
+receives this exception. One of the threads blocked on the same ``collaborative_once_flag``
+calls the ``Func`` object again. 
+
+collaborative_once_flag Class
+-----------------------------
+
+.. toctree::
+    :titlesonly:
+
+    collaborative_once_flag_cls.rst
+
+
+Example
+-------
+
+The following example shows a class in which the "Lazy initialization" pattern is implemented on 
+the "cachedProperty" field.
+
+
+.. code:: cpp
+
+    #include "oneapi/tbb/collaborative_call_once.h"
+
+    extern double foo(int i);
+
+    class LazyData {
+        oneapi::tbb::collaborative_once_flag flag;
+        double cachedProperty;
+    public:
+        double getProperty() {
+            oneapi::tbb::collaborative_call_once(flag, [&] {
+                // serial part
+                double result{};
+
+                // parallel part where threads can collaborate
+                result = oneapi::tbb::parallel_reduce(oneapi::tbb::blocked_range<int>(0, 1000),
+                    [&] (auto r, double r) {
+                        for(int i = r.begin(); i != r.end(); ++i) {
+                            r += foo(i);
+                        }
+                        return r;
+                    },
+                    std::plus<double, double>{}
+                );
+
+                // continue serial part
+                cachedProperty = result;
+            });
+
+            return cachedProperty;
+        }
+    };