[oneTBB] Add the Core Types preference API to the spec (#394)

Signed-off-by: Kochin Ivan <kochin.ivan@intel.com>
Co-authored-by: Aleksei Fedotov <aleksei.fedotov@intel.com>

Author: Ivan Kochin

source/elements/oneTBB/source/info_namespace.rst

@@ -16,8 +16,13 @@ Interfaces to query information about execution environment.
     namespace oneapi {
     namespace tbb {
         using numa_node_id = /*implementation-defined*/;
+        using core_type_id = /*implementation-defined*/;
+
         namespace info {
             std::vector<numa_node_id> numa_nodes();
+            std::vector<core_type_id> core_types();
+
+            int default_concurrency(task_arena::constraints c);
             int default_concurrency(numa_node_id id = oneapi::tbb::task_arena::automatic);
         }
     } // namespace tbb
@@ -39,6 +44,19 @@ Functions
         If error occurs during system topology parsing, returns vector containing single element
         that equals to ``task_arena::automatic``.
 
+.. cpp:function:: std::vector<core_type_id> core_types()
+
+    Returns the vector of integral indexes that indicate available core types.
+    The indexes are sorted from the least performant to the most performant core type.
+
+    .. note::
+        If error occurs during system topology parsing, returns vector containing single element
+        that equals to ``task_arena::automatic``.
+
+.. cpp:function:: int default_concurrency(task_arena::constraints c)
+
+    Returns concurrency level for the given constraints.
+
 .. cpp:function:: int default_concurrency(numa_node_id id = oneapi::tbb::task_arena::automatic)
 
     Returns concurrency level of the given NUMA node. If argument is not specified, returns default

source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst

@@ -27,11 +27,18 @@ A class that represents an explicit, user-managed task scheduler arena.
                 };
 
                 struct constraints {
-                    numa_node_id numa_node;
-                    int max_concurrency;
-
                     constraints(numa_node_id numa_node_       = task_arena::automatic,
                                 int          max_concurrency_ = task_arena::automatic);
+
+                    constraints& set_numa_id(numa_node_id id);
+                    constraints& set_max_concurrency(int maximal_concurrency);
+                    constraints& set_core_type(core_type_id id);
+                    constraints& set_max_threads_per_core(int threads_number);
+
+                    numa_node_id numa_id = task_arena::automatic;
+                    int max_concurrency = task_arena::automatic;
+                    core_type_id core_type = task_arena::automatic;
+                    int max_threads_per_core = task_arena::automatic;
                 };
 
                 task_arena(int max_concurrency = automatic, unsigned reserved_for_masters = 1,
@@ -113,16 +120,61 @@ Member types and constants
 
     Represents limitations applied to threads within ``task_arena``.
 
-    ``numa_node`` - An integral logical index uniquely identifying a NUMA node.
-    All threads joining the ``task_arena`` are bound to this NUMA node.
+    Starting from C++20 this class should be an aggregate type to support the designated initialization.
+
+.. cpp:member:: numa_node_id constraints::numa_id
+
+    An integral logical index uniquely identifying a NUMA node.
+    If set to non-automatic value, then this NUMA node will be considered as preferred for all the
+    threads within the arena.
 
     .. note::
 
         NUMA node ID is considered valid if it was obtained through tbb::info::numa_nodes().
 
-    ``max_concurrency`` - The maximum number of threads that can participate in work processing
+.. cpp:member:: int constraints::max_concurrency
+
+    The maximum number of threads that can participate in work processing
     within the ``task_arena`` at the same time.
 
+.. cpp:member:: core_type_id constraints::core_type
+
+    An integral logical index uniquely identifying a core type.
+    If set to non-automatic value, then this core type will be considered as preferred for all the
+    threads within the arena.
+
+    .. note::
+
+        core type ID is considered valid if it was obtained through ``tbb::info::core_types()``.
+
+.. cpp:member:: int constraints::max_threads_per_core
+
+    The maximum number of threads that can be scheduled to one core simultaneously.
+
+.. cpp:function:: constraints::constraints(numa_node_id numa_node_ = task_arena::automatic, int max_concurrency_ = task_arena::automatic)
+
+    Constructs the constraints object with the provided `numa_id` and `max_concurrency` settings.
+
+    .. note::
+
+        To support designated initialization this constructor is omitted starting from C++20. Aggregate initialization is supposed to be used instead.
+
+.. cpp:function:: constraints& constraints::set_numa_id(numa_node_id id)
+
+    Sets the `numa_id` to the provided ``id``. Returns the reference to the updated constraints object.
+
+.. cpp:function:: constraints& constraints::set_max_concurrency(int maximal_concurrency)
+
+    Sets the `max_concurrency` to the provided ``maximal_concurrency``. Returns the reference to the updated constraints object.
+
+.. cpp:function:: constraints& constraints::set_core_type(core_type_id id)
+
+    Sets the `core_type` to the provided ``id``. Returns the reference to the updated constraints object.
+
+.. cpp:function:: constraints& constraints::set_max_threads_per_core(int threads_number)
+
+    Sets the `max_threads_per_core` to the provided ``threads_number``. Returns the reference to the updated constraints object.
+
 Member functions
 ----------------