diff --git a/pep-0670.rst b/pep-0670.rst index 4381c3551..9a8a8e8ed 100644 --- a/pep-0670.rst +++ b/pep-0670.rst @@ -15,7 +15,8 @@ Abstract Convert macros to static inline functions or regular functions. Remove the return value of macros having a return value, whereas they -should not, to detect bugs in C extensions when the C API is misused. +should not, to aid detecting bugs in C extensions when the C API is +misused. Some function arguments are still cast to ``PyObject*`` to prevent emitting new compiler warnings. @@ -25,8 +26,8 @@ Rationale ========= The use of macros may have unintended adverse effects that are hard to -avoid, even for experienced C developers. Some issues have been known for -years, while others have been discovered recently in Python. +avoid, even for experienced C developers. Some issues have been known +for years, while others have been discovered recently in Python. Working around macro pitfalls makes the macro coder harder to read and to maintain. @@ -67,9 +68,9 @@ common macro pitfalls: Performance and inlining ======================== -Static inline functions is a feature added to the C99 standard. Modern -C compilers have efficient heuristics to decide if a function should be inlined -or not. +Static inline functions is a feature added to the C99 standard. Modern C +compilers have efficient heuristics to decide if a function should be +inlined or not. When a C compiler decides to not inline, there is likely a good reason. For example, inlining would reuse a register which require to @@ -90,8 +91,8 @@ decide if function should be inlined or not. Force inlining -------------- -The ``Py_ALWAYS_INLINE`` macro can be used to force inlining. This macro uses -``__attribute__((always_inline))`` with GCC and Clang, and +The ``Py_ALWAYS_INLINE`` macro can be used to force inlining. This macro +uses ``__attribute__((always_inline))`` with GCC and Clang, and ``__forceinline`` with MSC. So far, previous attempts to use ``Py_ALWAYS_INLINE`` didn't show any @@ -163,7 +164,8 @@ functions. The performance impact of such conversion should be measured with benchmarks. If there is a significant slowdown, there should be a good -reason to do the conversion. One reason can be hiding implementation details. +reason to do the conversion. One reason can be hiding implementation +details. Using static inline functions in the internal C API is fine: the internal C API exposes implemenation details by design and should not be @@ -191,8 +193,8 @@ For example, the ``Py_TYPE(obj)`` macro casts its ``obj`` argument to The undocumented private ``_Py_TYPE()`` function must not be called directly. Only the documented public ``Py_TYPE()`` macro must be used. -Later, the cast can be removed on a case by case basis, but that is out of -scope for this PEP. +Later, the cast can be removed on a case by case basis, but that is out +of scope for this PEP. Remove the return value ----------------------- @@ -205,8 +207,8 @@ misused in third party C extensions. See `bpo-30459 notice this issue while reviewing macro code. These macros are converted to functions using the ``void`` return type -to remove their return value. Removing the return value aids detecting bugs in -C extensions when the C API is misused. +to remove their return value. Removing the return value aids detecting +bugs in C extensions when the C API is misused. Backwards Compatibility