From 2ecfcf5afc492275e5c8899fc6704f5d812903de Mon Sep 17 00:00:00 2001 From: Ivan Kochin Date: Tue, 20 Dec 2022 21:36:17 +0400 Subject: [PATCH] Moving the Hybrid CPUs API out of preview (#680) Move the Hybrid CPUs API out of preview. This patch removes the necessity of setting the preview macro and removes the API reference topic Signed-off-by: Kochin Ivan Co-authored-by: Kochin Ivan Co-authored-by: Isaev, Ilya Co-authored-by: Alexandra --- doc/main/reference/constraints_extensions.rst | 118 ------------------ .../reference/info_namespace_extensions.rst | 71 ----------- doc/main/reference/reference.rst | 2 - .../Guiding_Task_Scheduler_Execution.rst | 5 +- .../snippets/flow_graph_examples.cpp | 4 - include/oneapi/tbb/detail/_config.h | 4 - include/oneapi/tbb/info.h | 12 +- include/oneapi/tbb/task_arena.h | 9 -- src/tbb/arena.cpp | 10 -- test/common/common_arena_constraints.h | 4 +- .../conformance_arena_constraints.cpp | 17 ++- test/tbb/test_arena_constraints.cpp | 17 +-- 12 files changed, 22 insertions(+), 251 deletions(-) delete mode 100644 doc/main/reference/constraints_extensions.rst delete mode 100644 doc/main/reference/info_namespace_extensions.rst diff --git a/doc/main/reference/constraints_extensions.rst b/doc/main/reference/constraints_extensions.rst deleted file mode 100644 index 84ba9e8622..0000000000 --- a/doc/main/reference/constraints_extensions.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _constraints_extensions: - -task_arena::constraints extensions -====================================== - -.. note:: - To enable this feature, set the ``TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION`` macro to 1. - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -These extensions allow to customize ``tbb::task_arena::constraints`` with the following properties: - -* On machines with IntelĀ® Hybrid Technology set the preferred core type for threads working within the task arena. -* Limit the maximum number of threads that can be scheduled to one core simultaneously. - -API -*** - -Header ------- - -.. code:: cpp - - #include - -Synopsis --------- - -.. code:: cpp - - namespace oneapi { - namespace tbb { - - class task_arena { - public: - struct constraints { - 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; - }; // struct constraints - }; // class task_arena - - } // namespace tbb - } // namespace oneapi - -Member Functions ----------------- - -.. cpp:function:: constraints& set_numa_id(numa_node_id id) - - Sets the ``numa_id`` field to the ``id``. - - **Returns:** Reference to ``*this``. - -.. cpp:function:: constraints& set_max_concurrency(int maximal_concurrency) - - Sets the ``max_concurrency`` field to the ``maximal_concurrency``. - - **Returns:** Reference to ``*this``. - -.. cpp:function:: constraints& set_core_type(core_type_id id) - - Sets the ``core_type`` field to the ``id``. - - **Returns:** Reference to ``*this``. - -.. cpp:function:: constraints& set_max_threads_per_core(int threads_number) - - Sets the ``max_threads_per_core`` field to the ``threads_number``. - - **Returns:** Reference to ``*this``. - -Member Objects --------------- - -.. cpp:member:: numa_node_id numa_id - - An integral logical index uniquely identifying a NUMA node. All threads joining the - ``task_arena`` are bound to this NUMA node. - - .. note:: - - To obtain a valid NUMA node ID, call ``oneapi::tbb::info::numa_nodes()``. - -.. cpp:member:: int 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 core_type - - An integral logical index uniquely identifying a core type. All threads joining the - ``task_arena`` are bound to this core type. - - .. note:: - - To obtain a valid core type node ID, call ``oneapi::tbb::info::core_types()``. - -.. cpp:member:: int max_threads_per_core - - The maximum number of threads that can be scheduled to one core simultaneously. - -See also: - -* :doc:`oneapi::tbb::info namespace preview extensions ` -* `oneapi::tbb::task_arena specification `_ diff --git a/doc/main/reference/info_namespace_extensions.rst b/doc/main/reference/info_namespace_extensions.rst deleted file mode 100644 index 4f851ae016..0000000000 --- a/doc/main/reference/info_namespace_extensions.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _info_namespace_extensions: - -oneapi::tbb::info namespace extensions -====================================== - -.. note:: - To enable this feature, set the ``TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION`` macro to 1. - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -These extensions allow to query information about execution environment. - -.. contents:: - :local: - :depth: 1 - -API -*** - -Header ------- - -.. code:: cpp - - #include - -Syntax ------- - -.. code:: cpp - - namespace oneapi { - namespace tbb { - using core_type_id = /*implementation-defined*/; - namespace info { - std::vector core_types(); - int default_concurrency(task_arena::constraints c); - } - } - } - -Types ------ - -``core_type_id`` - Represents core type identifier. - -Functions ---------- - -.. cpp:function:: std::vector 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. - -See also: - -* :doc:`task_arena::constraints class preview extensions ` -* `info namespace specification `_ diff --git a/doc/main/reference/reference.rst b/doc/main/reference/reference.rst index 8990508206..9c8bca526a 100644 --- a/doc/main/reference/reference.rst +++ b/doc/main/reference/reference.rst @@ -47,7 +47,5 @@ The key properties of a preview feature are: scalable_memory_pools helpers_for_expressing_graphs concurrent_lru_cache_cls - constraints_extensions - info_namespace_extensions task_group_extensions custom_mutex_chmap diff --git a/doc/main/tbb_userguide/Guiding_Task_Scheduler_Execution.rst b/doc/main/tbb_userguide/Guiding_Task_Scheduler_Execution.rst index 3d770c794b..b0b33fe498 100644 --- a/doc/main/tbb_userguide/Guiding_Task_Scheduler_Execution.rst +++ b/doc/main/tbb_userguide/Guiding_Task_Scheduler_Execution.rst @@ -61,8 +61,9 @@ assign a NUMA node identifier to the ``task_arena::constraints::numa_id`` field. The processors with `IntelĀ® Hybrid Technology `_ contain several core types, each is suited for different purposes. -For example, some applications may improve their performance by preferring execution on the most performant cores. -To set execution preference, assign specific core type identifier to the ``task_arena::constraints::core_type`` field. +In most cases, systems with hybrid CPU architecture show reasonable performance without involving additional API calls. +However, in some exceptional scenarios, performance may be tuned by setting the preferred core type. +To set the preferred core type for the execution, assign a specific core type identifier to the ``task_arena::constraints::core_type`` field. The example shows how to set the most performant core type as preferable for work execution: diff --git a/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp b/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp index c1b97975c3..72c594c5c7 100644 --- a/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp +++ b/doc/main/tbb_userguide/snippets/flow_graph_examples.cpp @@ -17,10 +17,6 @@ /* Flow Graph Code Example for the Userguide. */ -//! Enable extended task_arena constraints feature for supporting Intel Hybrid Technology -//! and Intel Hyper-Threading Technology. -#define TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION 1 - #include #include diff --git a/include/oneapi/tbb/detail/_config.h b/include/oneapi/tbb/detail/_config.h index 9bc2ed502f..b04072fe05 100644 --- a/include/oneapi/tbb/detail/_config.h +++ b/include/oneapi/tbb/detail/_config.h @@ -374,10 +374,6 @@ #define __TBB_ARENA_BINDING 1 #endif -#if (TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION || __TBB_BUILD) && __TBB_ARENA_BINDING - #define __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT 1 -#endif - #ifndef __TBB_ENQUEUE_ENFORCED_CONCURRENCY #define __TBB_ENQUEUE_ENFORCED_CONCURRENCY 1 #endif diff --git a/include/oneapi/tbb/info.h b/include/oneapi/tbb/info.h index 5a68960a84..dfcfcc031d 100644 --- a/include/oneapi/tbb/info.h +++ b/include/oneapi/tbb/info.h @@ -1,5 +1,5 @@ /* - Copyright (c) 2019-2021 Intel Corporation + Copyright (c) 2019-2022 Intel Corporation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -49,7 +49,6 @@ struct constraints { max_concurrency = maximal_concurrency; return *this; } -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT constraints& set_core_type(core_type_id id) { core_type = id; return *this; @@ -58,14 +57,11 @@ struct constraints { max_threads_per_core = threads_number; return *this; } -#endif numa_node_id numa_id = -1; int max_concurrency = -1; -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT core_type_id core_type = -1; int max_threads_per_core = -1; -#endif }; } // namespace d1 @@ -96,7 +92,6 @@ inline int default_concurrency(numa_node_id id = -1) { return r1::numa_default_concurrency(id); } -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT inline std::vector core_types() { std::vector core_type_indexes(r1::core_type_count()); r1::fill_core_type_indices(core_type_indexes.data()); @@ -107,22 +102,17 @@ inline int default_concurrency(constraints c) { if (c.max_concurrency > 0) { return c.max_concurrency; } return r1::constraints_default_concurrency(c); } -#endif /*__TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT*/ } // namespace d1 } // namespace detail inline namespace v1 { using detail::d1::numa_node_id; -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT using detail::d1::core_type_id; -#endif namespace info { using detail::d1::numa_nodes; -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT using detail::d1::core_types; -#endif using detail::d1::default_concurrency; } // namespace info diff --git a/include/oneapi/tbb/task_arena.h b/include/oneapi/tbb/task_arena.h index 69c8b94765..0de49aef07 100644 --- a/include/oneapi/tbb/task_arena.h +++ b/include/oneapi/tbb/task_arena.h @@ -187,13 +187,8 @@ class task_arena_base { , my_num_reserved_slots(reserved_for_masters) , my_priority(a_priority) , my_numa_id(constraints_.numa_id) -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT , my_core_type(constraints_.core_type) , my_max_threads_per_core(constraints_.max_threads_per_core) -#else - , my_core_type(automatic) - , my_max_threads_per_core(automatic) -#endif {} #endif /*__TBB_ARENA_BINDING*/ public: @@ -280,10 +275,8 @@ class task_arena : public task_arena_base { constraints{} .set_numa_id(s.my_numa_id) .set_max_concurrency(s.my_max_concurrency) -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT .set_core_type(s.my_core_type) .set_max_threads_per_core(s.my_max_threads_per_core) -#endif , s.my_num_reserved_slots, s.my_priority) {} #else @@ -337,10 +330,8 @@ class task_arena : public task_arena_base { if( !is_active() ) { my_numa_id = constraints_.numa_id; my_max_concurrency = constraints_.max_concurrency; -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT my_core_type = constraints_.core_type; my_max_threads_per_core = constraints_.max_threads_per_core; -#endif my_num_reserved_slots = reserved_for_masters; my_priority = a_priority; r1::initialize(*this); diff --git a/src/tbb/arena.cpp b/src/tbb/arena.cpp index 2161ed5dc2..e79f689b82 100644 --- a/src/tbb/arena.cpp +++ b/src/tbb/arena.cpp @@ -436,17 +436,11 @@ void task_arena_impl::initialize(d1::task_arena_base& ta) { (void)governor::get_thread_data(); if (ta.my_max_concurrency < 1) { #if __TBB_ARENA_BINDING - -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT d1::constraints arena_constraints = d1::constraints{} .set_core_type(ta.core_type()) .set_max_threads_per_core(ta.max_threads_per_core()) .set_numa_id(ta.my_numa_id); ta.my_max_concurrency = (int)default_concurrency(arena_constraints); -#else /*!__TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT*/ - ta.my_max_concurrency = (int)default_concurrency(ta.my_numa_id); -#endif /*!__TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT*/ - #else /*!__TBB_ARENA_BINDING*/ ta.my_max_concurrency = (int)governor::default_num_threads(); #endif /*!__TBB_ARENA_BINDING*/ @@ -736,15 +730,11 @@ int task_arena_impl::max_concurrency(const d1::task_arena_base *ta) { #if __TBB_ARENA_BINDING if (ta) { -#if __TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT d1::constraints arena_constraints = d1::constraints{} .set_numa_id(ta->my_numa_id) .set_core_type(ta->core_type()) .set_max_threads_per_core(ta->max_threads_per_core()); return (int)default_concurrency(arena_constraints); -#else /*!__TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT*/ - return (int)default_concurrency(ta->my_numa_id); -#endif /*!__TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION_PRESENT*/ } #endif /*!__TBB_ARENA_BINDING*/ diff --git a/test/common/common_arena_constraints.h b/test/common/common_arena_constraints.h index 5844d396d7..2c84b2604a 100644 --- a/test/common/common_arena_constraints.h +++ b/test/common/common_arena_constraints.h @@ -1,5 +1,5 @@ /* - Copyright (c) 2019-2021 Intel Corporation + Copyright (c) 2019-2022 Intel Corporation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -17,8 +17,6 @@ #ifndef __TBB_test_common_arena_constraints_H_ #define __TBB_test_common_arena_constraints_H_ -#define TBB_PREVIEW_TASK_ARENA_CONSTRAINTS_EXTENSION 1 - #if _WIN32 || _WIN64 #define _CRT_SECURE_NO_WARNINGS #endif diff --git a/test/conformance/conformance_arena_constraints.cpp b/test/conformance/conformance_arena_constraints.cpp index 1f30d6ad59..de70fe8cc5 100644 --- a/test/conformance/conformance_arena_constraints.cpp +++ b/test/conformance/conformance_arena_constraints.cpp @@ -1,5 +1,5 @@ /* - Copyright (c) 2019-2021 Intel Corporation + Copyright (c) 2019-2022 Intel Corporation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -57,6 +57,21 @@ TEST_CASE("Test NUMA topology traversal correctness") { REQUIRE_MESSAGE(numa_nodes_info.empty(), "Some available NUMA nodes indexes were not detected."); } +#if __HYBRID_CPUS_TESTING +//! Testing NUMA topology traversal correctness +//! \brief \ref interface \ref requirement +TEST_CASE("Test core types topology traversal correctness") { + system_info::initialize(); + std::vector core_types_info = system_info::get_cpu_kinds_info(); + std::vector core_types = tbb::info::core_types(); + + REQUIRE_MESSAGE(core_types_info.size() == core_types.size(), "Wrong core types number detected."); + for (unsigned i = 0; i < core_types.size(); ++i) { + REQUIRE_MESSAGE(core_types[i] == core_types_info[i].index, "Wrong core type index detected."); + } +} +#endif /*__HYBRID_CPUS_TESTING*/ + #else /*!__TBB_HWLOC_VALID_ENVIRONMENT*/ //! Testing NUMA support interfaces validity when HWLOC is not presented on system diff --git a/test/tbb/test_arena_constraints.cpp b/test/tbb/test_arena_constraints.cpp index 227c2679bc..9264b87056 100644 --- a/test/tbb/test_arena_constraints.cpp +++ b/test/tbb/test_arena_constraints.cpp @@ -1,5 +1,5 @@ /* - Copyright (c) 2019-2021 Intel Corporation + Copyright (c) 2019-2022 Intel Corporation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -22,21 +22,6 @@ #include "tbb/parallel_for.h" #if __TBB_HWLOC_VALID_ENVIRONMENT -#if __HYBRID_CPUS_TESTING -//! Testing NUMA topology traversal correctness -//! \brief \ref interface \ref requirement -TEST_CASE("Test core types topology traversal correctness") { - system_info::initialize(); - std::vector core_types_info = system_info::get_cpu_kinds_info(); - std::vector core_types = tbb::info::core_types(); - - REQUIRE_MESSAGE(core_types_info.size() == core_types.size(), "Wrong core types number detected."); - for (unsigned i = 0; i < core_types.size(); ++i) { - REQUIRE_MESSAGE(core_types[i] == core_types_info[i].index, "Wrong core type index detected."); - } -} -#endif /*__HYBRID_CPUS_TESTING*/ - //! Test affinity and default_concurrency correctness for all available constraints. //! \brief \ref error_guessing TEST_CASE("Test affinity and default_concurrency correctness for all available constraints.") {