Add a placeholder CORRADE_BUILD_CPU_RUNTIME_DISPATCH option.

To be used by code that actually provides multiple variants. Enabled by
default only on platforms that have IFUNC support, elsewhere it's
currently disabled because I'm not yet sure about perf consequences of
going through a function pointer.

Author: mosra

CMakeLists.txt

@@ -252,6 +252,11 @@ else()
 endif()
 cmake_dependent_option(CORRADE_CPU_USE_IFUNC "Allow using GNU IFUNC for runtime CPU dispatch" ${_CORRADE_CPU_USE_IFUNC_DEFAULT} "_CORRADE_CPU_CAN_USE_IFUNC" OFF)
 
+# Runtime CPU dispatch. Because going through a function pointer may have
+# negative perf consequences, enable it by default only on platforms that have
+# IFUNC, and thus can avoid the function pointer indirection.
+option(CORRADE_BUILD_CPU_RUNTIME_DISPATCH "Build with runtime dispatch for CPU-dependent functionality" ${_CORRADE_CPU_CAN_USE_IFUNC})
+
 # Backwards compatibility for unprefixed CMake options. If the user isn't
 # explicitly using prefixed options in the first run already, accept the
 # unprefixed options, and remember this decision for subsequent runs

doc/building-corrade.dox

@@ -550,6 +550,17 @@ Options controlling the build:
     Corrade features simultaneously in multiple threads. Enabled by default,
     disable if you don't need this and don't want to pay potential performance
     penalties coming from thread-local variables.
+-   `CORRADE_BUILD_CPU_RUNTIME_DISPATCH` --- Build with performance-critical
+    code paths optimized for multiple architectures (such as SSE or AVX on
+    x86), with the best matching variant selected at runtime based on detected
+    CPU features. If not enabled, the library is built with just a single
+    variant that's picked at compile time depending on target architecture
+    flags being passed to the compiler. Enabled by default on platforms that
+    support [GNU IFUNC](https://sourceware.org/glibc/wiki/GNU_IFUNC), which is
+    currently only Linux with glibc and Android with API 30+. See also the
+    `CORRADE_CPU_USE_IFUNC` option below and
+    @ref Cpu-usage-automatic-cached-dispatch for details and information about
+    performance tradeoffs.
 
 Platform-specific options:
 

doc/corrade-changelog.dox

@@ -364,6 +364,13 @@ namespace Corrade {
     Windows as well instead of declaring aligned memory allocation functions on
     its own, as it's not worth the seriously-looking compiler warnings (see
     [mosra/corrade#145](https://github.com/mosra/corrade/issues/145))
+-   Platforms that support @ref CORRADE_CPU_USE_IFUNC will now build certain
+    code paths optimized for multiple architectures, with the best variant
+    selected at runtime using the @ref Cpu library based on available CPU
+    features. This behavior can be disabled with the
+    @ref CORRADE_BUILD_CPU_RUNTIME_DISPATCH CMake option. Platforms without
+    IFUNC support implement runtime dispatch using function pointers instead of
+    indirect functions and have this currently disabled by default.
 
 @subsection corrade-changelog-latest-bugfixes Bug fixes
 

doc/corrade-cmake.dox

@@ -211,6 +211,9 @@ also available as preprocessor variables if you include
 -   `CORRADE_BUILD_MULTITHREADED` --- Defined if compiled in a way that makes
     it possible to safely use certain Corrade features simultaneously in
     multiple threads.
+-   `CORRADE_BUILD_CPU_RUNTIME_DISPATCH` --- Defined if built with code paths
+    optimized for multiple architectres with the best matching variant selected
+    at runtime based on detected CPU features
 -   `CORRADE_TARGET_UNIX` --- Defined if compiled for some Unix flavor (Linux,
     BSD, macOS, iOS, Android, ...)
 -   `CORRADE_TARGET_APPLE` --- Defined if compiled for Apple platforms

modules/FindCorrade.cmake

@@ -80,6 +80,9 @@
 #  CORRADE_BUILD_MULTITHREADED  - Defined if compiled in a way that makes it
 #   possible to safely use certain Corrade features simultaneously in multiple
 #   threads
+#  CORRADE_BUILD_CPU_RUNTIME_DISPATCH - Defined if built with code paths
+#   optimized for multiple architectres with the best matching variant selected
+#   at runtime based on detected CPU features
 #  CORRADE_TARGET_UNIX          - Defined if compiled for some Unix flavor
 #   (Linux, BSD, macOS)
 #  CORRADE_TARGET_APPLE         - Defined if compiled for Apple platforms
@@ -321,6 +324,7 @@ set(_corradeFlags
     BUILD_STATIC
     BUILD_STATIC_UNIQUE_GLOBALS
     BUILD_MULTITHREADED
+    BUILD_CPU_RUNTIME_DISPATCH
     TARGET_UNIX
     TARGET_APPLE
     TARGET_IOS

src/Corrade/Corrade.h

@@ -115,6 +115,25 @@ read/write access to global data.
 #define CORRADE_BUILD_MULTITHREADED
 #undef CORRADE_BUILD_MULTITHREADED
 
+/**
+@brief Build with runtime CPU dispatch
+@m_since_latest
+
+Defined if the library is built with performance-critical code paths optimized
+for multiple architectures (such as SSE or AVX on x86), with the best matching
+variant selected at runtime based on detected CPU features. If not defined, the
+library is built with just a single variant that's picked at compile time
+depending on target architecture flags being passed to the compiler.
+
+The actual feature detection and dispatch both in the runtime and compile-time
+scenario is performed by the @relativeref{Corrade,Cpu} library. See
+@ref Cpu-usage-automatic-cached-dispatch for details and information about
+performance tradeoffs.
+@see @see @ref CORRADE_CPU_USE_IFUNC, @ref building-corrade, @ref corrade-cmake
+*/
+#define CORRADE_BUILD_CPU_RUNTIME_DISPATCH
+#undef CORRADE_BUILD_CPU_RUNTIME_DISPATCH
+
 /**
 @brief Debug build
 

src/Corrade/configure.h.cmake

@@ -34,6 +34,7 @@
 #cmakedefine CORRADE_BUILD_STATIC
 #cmakedefine CORRADE_BUILD_STATIC_UNIQUE_GLOBALS
 #cmakedefine CORRADE_BUILD_MULTITHREADED
+#cmakedefine CORRADE_BUILD_CPU_RUNTIME_DISPATCH
 
 #cmakedefine CORRADE_TARGET_APPLE
 #cmakedefine CORRADE_TARGET_IOS