Convert macros to static inline functions

Most macros will be converted to static inline functions.

The following macros will not be converted:

• Object-like macros (i.e. those which don’t need parentheses andarguments). For example:
  • Empty macros. Example:#definePy_HAVE_CONDVAR.
  • Macros only defining a value, even if a constant with a well definedtype would be better. Example:#defineMETH_VARARGS0x0001.
• Compatibility layer for different C compilers, C language extensions,or recent C features.Example:Py_GCC_ATTRIBUTE(),Py_ALWAYS_INLINE,Py_MEMCPY().
• Macros used for definitions rather than behavior.Example:PyAPI_FUNC,Py_DEPRECATED,Py_PYTHON_H.
• Macros that need C preprocessor features, like stringification andconcatenation. Example:Py_STRINGIFY().
• Macros which cannot be converted to functions. Examples:Py_BEGIN_ALLOW_THREADS (contains an unpaired}),Py_VISIT(relies on specific variable names), Py_RETURN_RICHCOMPARE (returnsfrom the calling function).
• Macros which can be used as an l-value in assignments. This would bean incompatible change and is out of the scope of this PEP.Example:PyBytes_AS_STRING().
• Macros which have different return types depending on the code pathor arguments.

Convert static inline functions to regular functions

Static inline functions in the public C API may be converted to regularfunctions, but only if there is no measurable performance impact ofchanging the function.The performance impact should be measured with benchmarks.

Cast pointer arguments

Currently, most macros accepting pointers cast pointer arguments totheir expected types. For example, in Python 3.6, thePy_TYPE()macro casts its argument toPyObject*:

#define Py_TYPE(ob) (((PyObject*)(ob))->ob_type)

ThePy_TYPE() macro accepts thePyObject* type, but also anypointer types, such asPyLongObject* andPyDictObject*.

Functions are strongly typed, and can only accept one type of argument.

To avoid compiler errors and warnings in existing code, when a macro isconverted to a function and the macro casts at least one of its argumentsa new macro will be added to keep the cast. The new macroand the function will have the same name.

Example with thePy_TYPE()macro converted to a static inline function:

staticinlinePyTypeObject*Py_TYPE(PyObject*ob){returnob->ob_type;}#define Py_TYPE(ob) Py_TYPE((PyObject*)(ob))

The cast is kept for all pointer types, not onlyPyObject*.This includes casts tovoid*: removing a cast tovoid* would emita new warning if the function is called with aconstvoid* variable.For example, thePyUnicode_WRITE() macro casts itsdata argument tovoid*, and so it currently acceptsconstvoid* type, even thoughit writes intodata. This PEP will not change this.

staticinlinePyTypeObject*Py_TYPE(PyObject*ob){returnob->ob_type;}#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000#  define Py_TYPE(ob) Py_TYPE((PyObject*)(ob))#endif

Return type is not changed

When a macro is converted to a function, its return type must not changeto prevent emitting new compiler warnings.

For example, Python 3.7 changed the return type ofPyUnicode_AsUTF8()fromchar* toconstchar* (commit).The change emitted new compiler warnings when building C extensionsexpectingchar*. This PEP doesn’t change the return type to preventthis issue.

Duplication of side effects

Macros:

#define PySet_Check(ob) \    (Py_IS_TYPE(ob, &PySet_Type) \     || PyType_IsSubtype(Py_TYPE(ob), &PySet_Type))#define Py_IS_NAN(X) ((X) != (X))

If theop or theX argument has a side effect, the side effect isduplicated: it executed twice byPySet_Check() andPy_IS_NAN().

For example, thepos++ argument in thePyUnicode_WRITE(kind,data,pos++,ch) code has a side effect.This code is safe because thePyUnicode_WRITE() macro only uses its3rd argument once and so does not duplicatepos++ side effect.

Misnesting

Example of thebpo-43181: Python macros don’t shield arguments. ThePyObject_TypeCheck()macro before it has been fixed:

#define PyObject_TypeCheck(ob, tp) \    (Py_IS_TYPE(ob, tp) || PyType_IsSubtype(Py_TYPE(ob), (tp)))

C++ usage example:

PyObject_TypeCheck(ob,U(f<a,b>(c)))

The preprocessor first expands it:

(Py_IS_TYPE(ob,f<a,b>(c))||...)

C++"<" and">" characters are not treated as brackets by thepreprocessor, so thePy_IS_TYPE() macro is invoked with 3 arguments:

• ob
• f<a
• b>(c)

The compilation fails with an error onPy_IS_TYPE() which only takes2 arguments.

The bug is that theop andtp arguments ofPyObject_TypeCheck()must be put between parentheses: replacePy_IS_TYPE(ob,tp) withPy_IS_TYPE((ob),(tp)). In regular C code, these parentheses areredundant, can be seen as a bug, and so are often forgotten when writingmacros.

To avoid Macro Pitfalls, thePyObject_TypeCheck() macro has beenconverted to a static inline function:commit.

PyObject_INIT()

Example showing the usage of commas in a macro which has a return value.

Python 3.7 macro:

#define PyObject_INIT(op, typeobj) \    ( Py_TYPE(op) = (typeobj), _Py_NewReference((PyObject *)(op)), (op) )

Python 3.8 function (simplified code):

staticinlinePyObject*_PyObject_INIT(PyObject*op,PyTypeObject*typeobj){Py_TYPE(op)=typeobj;_Py_NewReference(op);returnop;}#define PyObject_INIT(op, typeobj) \    _PyObject_INIT(_PyObject_CAST(op), (typeobj))

• The function doesn’t need the line continuation character"\".
• It has an explicit"returnop;" rather than the surprising",(op)" syntax at the end of the macro.
• It uses short statements on multiple lines, rather than being writtenas a single long line.
• Inside the function, theop argument has the well defined typePyObject* and so doesn’t need casts like(PyObject*)(op).
• Arguments don’t need to be put inside parentheses: usetypeobj,rather than(typeobj).

_Py_NewReference()

Example showing the usage of an#ifdef inside a macro.

Python 3.7 macro (simplified code):

#ifdef COUNT_ALLOCS#  define _Py_INC_TPALLOCS(OP) inc_count(Py_TYPE(OP))#  define _Py_COUNT_ALLOCS_COMMA  ,#else#  define _Py_INC_TPALLOCS(OP)#  define _Py_COUNT_ALLOCS_COMMA#endif/* COUNT_ALLOCS */#define _Py_NewReference(op) (                   \    _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA  \    Py_REFCNT(op) = 1)

Python 3.8 function (simplified code):

staticinlinevoid_Py_NewReference(PyObject*op){_Py_INC_TPALLOCS(op);Py_REFCNT(op)=1;}

PyUnicode_READ_CHAR()

This macro reuses arguments, and possibly callsPyUnicode_KIND multipletimes:

#define PyUnicode_READ_CHAR(unicode, index) \(assert(PyUnicode_Check(unicode)),          \ assert(PyUnicode_IS_READY(unicode)),       \ (Py_UCS4)                                  \    (PyUnicode_KIND((unicode)) == PyUnicode_1BYTE_KIND ? \        ((const Py_UCS1 *)(PyUnicode_DATA((unicode))))[(index)] : \        (PyUnicode_KIND((unicode)) == PyUnicode_2BYTE_KIND ? \            ((const Py_UCS2 *)(PyUnicode_DATA((unicode))))[(index)] : \            ((const Py_UCS4 *)(PyUnicode_DATA((unicode))))[(index)] \        ) \    ))

Possible implementation as a static inlined function:

staticinlinePy_UCS4PyUnicode_READ_CHAR(PyObject*unicode,Py_ssize_tindex){assert(PyUnicode_Check(unicode));assert(PyUnicode_IS_READY(unicode));switch(PyUnicode_KIND(unicode)){casePyUnicode_1BYTE_KIND:return(Py_UCS4)((constPy_UCS1*)(PyUnicode_DATA(unicode)))[index];casePyUnicode_2BYTE_KIND:return(Py_UCS4)((constPy_UCS2*)(PyUnicode_DATA(unicode)))[index];casePyUnicode_4BYTE_KIND:default:return(Py_UCS4)((constPy_UCS4*)(PyUnicode_DATA(unicode)))[index];}}

Macros converted to static inline functions

Python 3.8:

• Py_DECREF()
• Py_INCREF()
• Py_XDECREF()
• Py_XINCREF()
• PyObject_INIT()
• PyObject_INIT_VAR()
• _PyObject_GC_UNTRACK()
• _Py_Dealloc()

Macros converted to regular functions

Python 3.9:

• PyIndex_Check()
• PyObject_CheckBuffer()
• PyObject_GET_WEAKREFS_LISTPTR()
• PyObject_IS_GC()
• PyObject_NEW(): alias toPyObject_New()
• PyObject_NEW_VAR(): alias toPyObjectVar_New()

To avoid performance slowdown on Python built without LTO,private static inline functions have been added to the internal C API:

• _PyIndex_Check()
• _PyObject_IS_GC()
• _PyType_HasFeature()
• _PyType_IS_GC()

Static inline functions converted to regular functions

Python 3.11:

• PyObject_CallOneArg()
• PyObject_Vectorcall()
• PyVectorcall_Function()
• _PyObject_FastCall()

To avoid performance slowdown on Python built without LTO, aprivate static inline function has been added to the internal C API:

• _PyVectorcall_FunctionInline()

Incompatible changes

While other converted macros didn’t break the backward compatibility,there is an exception.

The 3 macrosPy_REFCNT(),Py_TYPE() andPy_SIZE() have beenconverted to static inline functions in Python 3.10 and 3.11 to disallowusing them as l-value in assignment. It is an incompatible change madeon purpose: seebpo-39573 forthe rationale.

This PEP does not propose converting macros which can be used as l-valueto avoid introducing new incompatible changes.

Static inline functions

First of all, converting macros tostatic inline functions hasnegligible impact on performance: the measured differences are consistentwith noise due to unrelated factors.

Static inline functions are a new feature in the C99 standard. Modern Ccompilers have efficient heuristics to decide if a function should beinlined or not.

When a C compiler decides to not inline, there is likely a good reason.For example, inlining would reuse a register which requires tosave/restore the register value on the stack and so increases the stackmemory usage, or be less efficient.

Benchmark of the./python-mtest-j5 command on Python built inrelease mode withgcc-O3, LTO and PGO:

• Macros (PR 29728): 361 sec +- 1 sec
• Static inline functions (reference): 361 sec +- 1 sec

There isno significant performance difference between macros andstatic inline functions when static inline functionsare inlined.

Debug build

Performance in debug buildscan suffer when macros are converted tofunctions. This is compensated by better debuggability: debuggers canretrieve function names, set breakpoints inside functions, etc.

On Windows, when Python is built in debug mode by Visual Studio, staticinline functions are not inlined.

On other platforms,./configure--with-pydebug uses the-Og compileroption on compilers that support it (including GCC and LLVM Clang).-Og means “optimize debugging experience”.Otherwise, the-O0 compiler option is used.-O0 means “disable most optimizations”.

With GCC 11,gcc-Og can inline static inline functions, whereasgcc-O0 does not inline static inline functions.

Benchmark of the./python-mtest-j10 command on Python built indebug mode withgcc-O0 (that is, compiler optimizations,including inlining, are explicitly disabled):

• Macros (PR 29728): 345 sec ± 5 sec
• Static inline functions (reference): 360 sec ± 6 sec

Replacing macros with static inline functions makes Python1.04x slower when the compilerdoes not inline static inlinefunctions.

Note that benchmarks should not be run on a Python debug build.Moreover, using link-time optimization (LTO) and profile-guided optimization(PGO) is recommended for best performance and reliable benchmarks.PGO helps the compiler to decide if functions should be inlined or not.

Force inlining

ThePy_ALWAYS_INLINE macro can be used to force inlining. This macrouses__attribute__((always_inline)) with GCC and Clang, and__forceinline with MSC.

Previous attempts to usePy_ALWAYS_INLINE didn’t show any benefit, and wereabandoned. See for examplebpo-45094“Consider using__forceinline and__attribute__((always_inline)) onstatic inline functions (Py_INCREF,Py_TYPE) for debug build”.

When thePy_INCREF() macro was converted to a static inlinefunction in 2018 (commit),it was decided not to force inlining. The machine code was analyzed withmultiple C compilers and compiler options, andPy_INCREF() was alwaysinlined without having to force inlining. The only case where it was notinlined was the debug build. See discussion inbpo-35059 “ConvertPy_INCREF() andPyObject_INIT() to inlined functions”.

Disabling inlining

On the other side, thePy_NO_INLINE macro can be used to disableinlining. It can be used to reduce the stack memory usage, or to preventinlining on LTO+PGO builds, which generally inline code more aggressively:seebpo-33720. ThePy_NO_INLINE macro uses__attribute__((noinline)) with GCC andClang, and__declspec(noinline) with MSC.

This technique is available, though we currently don’t know a concretefunction for which it would be useful.Note that with macros, it is not possible to disable inlining at all.

Keep macros, but fix some macro issues

Macros are always “inlined” with any C compiler.

The duplication of side effects can be worked around in the caller ofthe macro.

People using macros should be considered “consenting adults”. People whofeel unsafe with macros should simply not use them.

These ideas are rejected because macrosare error prone, and it is too easyto miss a macro pitfall when writing and reviewing macro code. Moreover, macrosare harder to read and maintain than functions.