From 3d3a4beefed46df7aa3a477f2e511459ce06c4b0 Mon Sep 17 00:00:00 2001 From: Ken Jin Date: Fri, 7 Feb 2025 20:18:15 +0800 Subject: gh-128563: Document the tail-calling interpreter (GH-129728) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/using/configure.rst | 10 ++++++++++ Doc/whatsnew/3.14.rst | 25 +++++++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 629859e..101c435 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -618,6 +618,16 @@ also be used to improve performance. Enable computed gotos in evaluation loop (enabled by default on supported compilers). +.. option:: --with-tail-call-interp + + Enable interpreters using tail calls in CPython. If enabled, enabling PGO + (:option:`--enable-optimizations`) is highly recommended. This option specifically + requires a C compiler with proper tail call support, and the + `preserve_none `_ + calling convention. For example, Clang 19 and newer supports this feature. + + .. versionadded:: next + .. option:: --without-mimalloc Disable the fast :ref:`mimalloc ` allocator diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index a95fc7a..c788db3 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -68,6 +68,7 @@ Summary -- release highlights * :ref:`PEP 649: deferred evaluation of annotations ` * :ref:`PEP 741: Python Configuration C API ` * :ref:`PEP 761: Discontinuation of PGP signatures ` +* :ref:`A new tail-calling interpreter ` New features @@ -208,6 +209,30 @@ configuration mechanisms). .. seealso:: :pep:`741`. +.. _whatsnew314-tail-call: + +A new tail-calling interpreter +------------------------------ + +A new type of interpreter based on tail calls has been added to CPython. +For certain newer compilers, this interpreter provides +significantly better performance. Preliminary numbers on our machines suggest +anywhere from -3% to 30% faster Python code, and a geometric mean of 9-15% +faster on ``pyperformance`` depending on platform and architecture. + +This interpreter currently only works with Clang 19 and newer +on x86-64 and AArch64 architectures. However, we expect +that a future release of GCC will support this as well. + +This feature is opt-in for now. We highly recommend enabling profile-guided +optimization with the new interpreter as it is the only configuration we have +tested and can validate its improved performance. +For further information on how to build Python, see +:option:`--with-tail-call-interp`. + +(Contributed by Ken Jin in :gh:`128718`, with ideas on how to implement this +in CPython by Mark Shannon, Garret Gu, Haoran Xu, and Josh Haberman.) + Other language changes ====================== -- cgit v0.12