gh-128563: Document the tail-calling interpreter (GH-129728)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 629859e36cb654f3613a71687aa704ec07bc9153..101c43576b03148b90d242ff779b85efea31e269 100644 (file)
--- 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 <https://clang.llvm.org/docs/AttributeReference.html#preserve-none>`_
+   calling convention. For example, Clang 19 and newer supports this feature.
+
+   .. versionadded:: next
+
 .. option:: --without-mimalloc
 
    Disable the fast :ref:`mimalloc <mimalloc>` allocator

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index a95fc7a4b6a9fa455b3c770d0fec9eb1d980cea8..c788db31fc27ed5ba8ebe4ae275b9a10122a8b0f 100644 (file)
--- 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 <whatsnew314-pep649>`
 * :ref:`PEP 741: Python Configuration C API <whatsnew314-pep741>`
 * :ref:`PEP 761: Discontinuation of PGP signatures <whatsnew314-pep761>`
+* :ref:`A new tail-calling interpreter  <whatsnew314-tail-call>`
 
 
 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
 ======================