bpo-45116: Add the Py_ALWAYS_INLINE macro (GH-28390)

Add the Py_ALWAYS_INLINE macro to ask the compiler to always inline a
static inline function. The compiler can ignore it and decides to not
inline the function.

3 files changed, 44 insertions, 0 deletions

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 83824bb..aac28b1 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -111,6 +111,25 @@ complete listing.
 
    .. versionadded:: 3.3
 
+.. c:macro:: Py_ALWAYS_INLINE
+
+   Ask the compiler to always inline a static inline function. The compiler can
+   ignore it and decides to not inline the function.
+
+   It can be used to inline performance critical static inline functions when
+   building Python in debug mode with function inlining disabled. For example,
+   MSC disables function inlining when building in debug mode.
+
+   Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
+   worse performances (due to increased code size for example). The compiler is
+   usually smarter than the developer for the cost/benefit analysis.
+
+   It must be specified before the function return type. Usage::
+
+       static inline Py_ALWAYS_INLINE int random(void) { return 4; }
+
+   .. versionadded:: 3.11
+
 .. c:macro:: Py_CHARMASK(c)
 
    Argument must be a character or an integer in the range [-128, 127] or [0,
diff --git a/Include/pyport.h b/Include/pyport.h
index 0aaa4ee..af7fbe7 100644
--- a/Include/pyport.h
+++ b/Include/pyport.h
@@ -557,6 +557,28 @@ extern "C" {
 #define _Py_HOT_FUNCTION
 #endif
 
+// Ask the compiler to always inline a static inline function. The compiler can
+// ignore it and decides to not inline the function.
+//
+// It can be used to inline performance critical static inline functions when
+// building Python in debug mode with function inlining disabled. For example,
+// MSC disables function inlining when building in debug mode.
+//
+// Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
+// worse performances (due to increased code size for example). The compiler is
+// usually smarter than the developer for the cost/benefit analysis.
+//
+// It must be specified before the function return type. Usage:
+//
+//     static inline Py_ALWAYS_INLINE int random(void) { return 4; }
+#if defined(__GNUC__) || defined(__clang__) || defined(__INTEL_COMPILER)
+#  define Py_ALWAYS_INLINE __attribute__((always_inline))
+#elif defined(_MSC_VER)
+#  define Py_ALWAYS_INLINE __forceinline
+#else
+#  define Py_ALWAYS_INLINE
+#endif
+
 // Py_NO_INLINE
 // Disable inlining on a function. For example, it reduces the C stack
 // consumption: useful on LTO+PGO builds which heavily inline code (see
diff --git a/Misc/NEWS.d/next/C API/2021-09-16-18-05-20.bpo-45116.WxXewl.rst b/Misc/NEWS.d/next/C API/2021-09-16-18-05-20.bpo-45116.WxXewl.rst
new file mode 100644
index 0000000..cf3db5c
--- /dev/null
+++ b/Misc/NEWS.d/next/C API/2021-09-16-18-05-20.bpo-45116.WxXewl.rst
@@ -0,0 +1,3 @@
+Add the :c:macro:`Py_ALWAYS_INLINE` macro to ask the compiler to always
+inline a static inline function. The compiler can ignore it and decides to
+not inline the function. Patch by Victor Stinner.