[Python-checkins] bpo-45116: Add the Py_ALWAYS_INLINE macro (GH-28390)

[vstinner]

https://github.com/python/cpython/commit/6b413551284a94cfe31377c9c607ff890aa06c26
commit: 6b413551284a94cfe31377c9c607ff890aa06c26
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2021-09-17T14:09:14+02:00
summary:

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.

files:
A Misc/NEWS.d/next/C API/2021-09-16-18-05-20.bpo-45116.WxXewl.rst
M Doc/c-api/intro.rst
M Include/pyport.h

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 83824bb474fbd..aac28b1e77561 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 0aaa4eedd31a1..af7fbe7fc7195 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 0000000000000..cf3db5ca2a023
--- /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.