Debug build

When Python is built in debug mode, most compiler optimizations are disabled. For example, Visual Studio disables inlining. Benchmarks must not be run on a Python debug build, only on release build: using LTO and PGO is recommended for reliable benchmarks. PGO helps the compiler to 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 __forceinline with MSC.

So far, previous attempts to use Py_ALWAYS_INLINE didn’t show any benefit and were abandoned. See for example: bpo-45094: “Consider using __forceinline and __attribute__((always_inline)) on static inline functions (Py_INCREF, Py_TYPE) for debug build”.

When the Py_INCREF() macro was converted to a static inline functions in 2018 (commit), it was decided not to force inlining. The machine code was analyzed with multiple C compilers and compiler options: Py_INCREF() was always inlined without having to force inlining. The only case where it was not inlined was the debug build. See discussion in the bpo-35059: “Convert Py_INCREF() and PyObject_INIT() to inlined functions”.

Disable inlining

On the other side, the Py_NO_INLINE macro can be used to disable inlining. It is useful to reduce the stack memory usage. It is especially useful on a LTO+PGO build which is more aggressive to inline code: see bpo-33720. The Py_NO_INLINE macro uses __attribute__ ((noinline)) with GCC and Clang, and __declspec(noinline) with MSC.

Convert macros to static inline functions

Most macros should be converted to static inline functions to prevent macro pitfalls.

The following macros should not be converted:

• Empty macros. Example: #define Py_HAVE_CONDVAR.
• Macros only defining a number, even if a constant with a well defined type can better. Example: #define METH_VARARGS 0x0001.
• Compatibility layer for different C compilers, C language extensions, or recent C features. Example: #define Py_ALWAYS_INLINE __attribute__((always_inline)).

Convert static inline functions to regular functions

The performance impact of converting static inline functions to regular functions 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.

Using static inline functions in the internal C API is fine: the internal C API exposes implemenation details by design and should not be used outside Python.

Cast to PyObject*

When a macro is converted to a function and the macro casts its arguments to PyObject*, the new function comes with a new macro which cast arguments to PyObject* to prevent emitting new compiler warnings. So the converted functions still accept pointers to structures inheriting from PyObject (ex: PyTupleObject).

For example, the Py_TYPE(obj) macro casts its obj argument to PyObject*:

#define _PyObject_CAST_CONST(op) ((const PyObject*)(op))

static inline PyTypeObject* _Py_TYPE(const PyObject *ob) {
    return ob->ob_type;
}
#define Py_TYPE(ob) _Py_TYPE(_PyObject_CAST_CONST(ob))

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.

Remove the return value

When a macro is implemented as an expression, it has an implicit return value. In some cases, the macro must not have a return value and can be misused in third party C extensions. See bpo-30459 for the example of PyList_SET_ITEM() and PyCell_SET() macros. It is not easy to 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.

Keep macros, but fix some macro issues

Converting macros to functions is not needed to remove the return value: casting a macro return value to void also fix the issue. For example, the PyList_SET_ITEM() macro was already fixed like that.

Macros are always “inlined” with any C compiler.

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

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

_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):

static inline void _Py_NewReference(PyObject *op)
{
    _Py_INC_TPALLOCS(op);
    Py_REFCNT(op) = 1;
}

PyObject_INIT()

Example showing the usage of commas in a macro.

Python 3.7 macro:

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

Python 3.8 function (simplified code):

static inline PyObject*
_PyObject_INIT(PyObject *op, PyTypeObject *typeobj)
{
    Py_TYPE(op) = typeobj;
    _Py_NewReference(op);
    return op;
}

#define PyObject_INIT(op, typeobj) \
    _PyObject_INIT(_PyObject_CAST(op), (typeobj))

The function doesn’t need the line continuation character. It has an explicit "return op;" rather than a surprising ", (op)" at the end of the macro. It uses one short statement per line, rather than a single long line. Inside the function, the op argument has a well defined type: PyObject*.

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()

Python 3.10:

• Py_REFCNT()

Python 3.11:

• Py_TYPE()
• Py_SIZE()

Macros converted to regular functions

Python 3.9:

• PyIndex_Check()
• PyObject_CheckBuffer()
• PyObject_GET_WEAKREFS_LISTPTR()
• PyObject_IS_GC()
• PyObject_NEW(): alias to PyObject_New()
• PyObject_NEW_VAR(): alias to PyObjectVar_New()

To avoid any risk of 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 any risk of performance slowdown on Python built without LTO, a private static inline function has been added to the internal C API:

• _PyVectorcall_FunctionInline()