cpython/Include/cpython
Ken Jin 4fa80ce74c
gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310)
This PR changes the current JIT model from trace projection to trace recording. Benchmarking: better pyperformance (about 1.7% overall) geomean versus current https://raw.githubusercontent.com/facebookexperimental/free-threading-benchmarking/refs/heads/main/results/bm-20251108-3.15.0a1%2B-7e2bc1d-JIT/bm-20251108-vultr-x86_64-Fidget%252dSpinner-tracing_jit-3.15.0a1%2B-7e2bc1d-vs-base.svg, 100% faster Richards on the most improved benchmark versus the current JIT. Slowdown of about 10-15% on the worst benchmark versus the current JIT. **Note: the fastest version isn't the one merged, as it relies on fixing bugs in the specializing interpreter, which is left to another PR**. The speedup in the merged version is about 1.1%. https://raw.githubusercontent.com/facebookexperimental/free-threading-benchmarking/refs/heads/main/results/bm-20251112-3.15.0a1%2B-f8a764a-JIT/bm-20251112-vultr-x86_64-Fidget%252dSpinner-tracing_jit-3.15.0a1%2B-f8a764a-vs-base.svg

Stats: 50% more uops executed, 30% more traces entered the last time we ran them. It also suggests our trace lengths for a real trace recording JIT are too short, as a lot of trace too long aborts https://github.com/facebookexperimental/free-threading-benchmarking/blob/main/results/bm-20251023-3.15.0a1%2B-eb73378-CLANG%2CJIT/bm-20251023-vultr-x86_64-Fidget%252dSpinner-tracing_jit-3.15.0a1%2B-eb73378-pystats-vs-base.md .

This new JIT frontend is already able to record/execute significantly more instructions than the previous JIT frontend. In this PR, we are now able to record through custom dunders, simple object creation, generators, etc. None of these were done by the old JIT frontend. Some custom dunders uops were discovered to be broken as part of this work gh-140277

The optimizer stack space check is disabled, as it's no longer valid to deal with underflow.

Pros:
* Ignoring the generated tracer code as it's automatically created, this is only additional 1k lines of code. The maintenance burden is handled by the DSL and code generator.
* `optimizer.c` is now significantly simpler, as we don't have to do strange things to recover the bytecode from a trace.
* The new JIT frontend is able to handle a lot more control-flow than the old one.
* Tracing is very low overhead. We use the tail calling interpreter/computed goto interpreter to switch between tracing mode and non-tracing mode. I call this mechanism dual dispatch, as we have two dispatch tables dispatching to each other. Specialization is still enabled while tracing.
* Better handling of polymorphism. We leverage the specializing interpreter for this.

Cons:
* (For now) requires tail calling interpreter or computed gotos. This means no Windows JIT for now :(. Not to fret, tail calling is coming soon to Windows though https://github.com/python/cpython/pull/139962

Design:
* After each instruction, the `record_previous_inst` function/label is executed. This does as the name suggests.
* The tracing interpreter lowers bytecode to uops directly so that it can obtain "fresh" values at the point of lowering.
* The tracing version behaves nearly identical to the normal interpreter, in fact it even has specialization! This allows it to run without much of a slowdown when tracing. The actual cost of tracing is only a function call and writes to memory.
* The tracing interpreter uses the specializing interpreter's deopt to naturally form the side exit chains. This allows it to side exit chain effectively, without repeating much code. We force a re-specializing when tracing a deopt.
* The tracing interpreter can even handle goto errors/exceptions, but I chose to disable them for now as it's not tested.
* Because we do not share interpreter dispatch, there is should be no significant slowdown to the original specializing interpreter on tailcall and computed got with JIT disabled. With JIT enabled, there might be a slowdown in the form of the JIT trying to trace.
* Things that could have dynamic instruction pointer effects are guarded on. The guard deopts to a new instruction --- `_DYNAMIC_EXIT`.
2025-11-13 18:08:32 +00:00
..
abstract.h gh-130947: Add again PySequence_Fast() to the limited C API (#130948) 2025-03-13 13:00:57 +01:00
audit.h gh-135755: Use private names (_Py*) for header file guards new in 3.14 (GH-135921) 2025-06-26 13:05:01 +02:00
bytearrayobject.h gh-139871: Add bytearray.take_bytes([n]) to efficiently extract bytes (GH-140128) 2025-11-13 13:19:44 +00:00
bytesobject.h gh-129813, PEP 782: Add PyBytesWriter_Format() (#138824) 2025-09-12 14:21:57 +02:00
cellobject.h gh-127271: Replace use of PyCell_GET/SET (gh-127272) 2024-12-03 10:33:06 -08:00
ceval.h gh-125604: Move _Py_AuditHookEntry, etc. Out of pycore_runtime.h (gh-125605) 2024-10-18 09:26:08 -06:00
classobject.h gh-89653: PEP 670: Convert macros to functions (#99843) 2022-11-28 16:40:08 +01:00
code.h gh-70030: Remove _PyCode_ConstantKey() function (#139735) 2025-10-08 22:33:45 +02:00
compile.h gh-117411: move PyFutureFeatures to pycore_symtable.h and make it private (#117412) 2024-04-02 10:34:49 +00:00
complexobject.h gh-128813: soft-deprecate _Py_c_*() functions (GH-137261) 2025-08-01 09:40:12 +02:00
context.h gh-124872: Replace enter/exit events with "switched" (#125532) 2024-10-16 13:53:21 +02:00
critical_section.h gh-133296: Publicly expose critical section API that accepts PyMutex (gh-135899) 2025-07-21 17:25:43 -04:00
descrobject.h gh-106320: Move _PyMethodWrapper_Type to internal C API (#107064) 2023-07-22 20:57:59 +00:00
dictobject.h gh-128863: Deprecate private C API functions (#128864) 2025-01-22 11:04:19 +00:00
fileobject.h gh-106320: Remove private _Py_UniversalNewlineFgetsWithSize() (#108602) 2023-08-29 02:36:50 +00:00
fileutils.h gh-128863: Deprecate private C API functions (#128864) 2025-01-22 11:04:19 +00:00
floatobject.h gh-89653: PEP 670: Convert macros to functions (#99843) 2022-11-28 16:40:08 +01:00
frameobject.h gh-74929: Implement PEP 667 (GH-115153) 2024-05-04 12:12:10 +01:00
funcobject.h gh-139924: Add PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME event for function watchers (#139925) 2025-10-10 15:25:38 -07:00
genobject.h gh-120834: fix type of *_iframe field in _PyGenObject_HEAD declaration (#120835) 2024-06-24 10:23:38 +01:00
import.h gh-128911: Add PyImport_ImportModuleAttr() function (#128912) 2025-01-30 11:17:29 +00:00
initconfig.h GH-133711: Enable UTF-8 mode by default (PEP 686) (#133712) 2025-07-15 10:45:41 +01:00
listobject.h gh-112087: Make list_repr and list_length to be thread-safe (gh-114582) 2024-01-27 01:20:21 +09:00
longintrepr.h gh-135379: Move PyLong_CheckCompact to private header and rename it (GH-135707) 2025-06-19 13:09:09 +00:00
longobject.h gh-132639: Adds PyLong_AsNativeBytes, PyLong_FromNativeBytes and PyLong_FromUnsignedNativeBytes to the limited API (GH-132640) 2025-04-21 15:59:03 +01:00
marshal.h gh-79315: Add Include/cpython/marshal.h header (#139725) 2025-10-07 23:49:08 +02:00
memoryobject.h gh-106320: Remove private _PyManagedBuffer_Type (#108431) 2023-08-24 19:07:54 +02:00
methodobject.h gh-87347: Add parenthesis around PyXXX_Check() arguments (#92815) 2022-06-16 13:49:43 +02:00
modsupport.h gh-137210: Add a struct, slot & function for checking an extension's ABI (GH-137212) 2025-09-05 16:23:18 +02:00
monitoring.h gh-79315: Remove Include/pylock.h and Include/monitoring.h (#139731) 2025-10-08 00:49:24 +02:00
object.h gh-112075: Remove _PyObject_SetManagedDict() function (#139737) 2025-10-12 19:32:10 +02:00
objimpl.h gh-102013: Move PyUnstable_GC_VisitObjects() to Include/cpython/objimpl.h (#115560) 2024-02-16 15:49:13 +01:00
odictobject.h gh-87347: Add parenthesis around macro arguments (#93915) 2022-06-20 16:04:52 +02:00
picklebufobject.h gh-87347: Add parenthesis around PyXXX_Check() arguments (#92815) 2022-06-16 13:49:43 +02:00
pthread_stubs.h GH-110829: Ensure Thread.join() joins the OS thread (#110848) 2023-11-04 13:59:24 +00:00
pyatomic.h gh-129296: Fix pyatomic.h include paths (#129320) 2025-01-29 15:06:19 +00:00
pyatomic_gcc.h gh-131121: Fix _Py_atomic_store_char_relaxed memory order (gh-131122) 2025-03-12 09:03:04 -04:00
pyatomic_msc.h gh-117657: TSAN Fix races in PyMember_Get and PyMember_Set for C extensions (GH-123211) 2024-12-03 09:41:53 -05:00
pyatomic_std.h gh-117657: TSAN Fix races in PyMember_Get and PyMember_Set for C extensions (GH-123211) 2024-12-03 09:41:53 -05:00
pyctype.h bpo-43816: Add extern "C" to Include/cpython/pyctype.h (GH-25365) 2021-04-13 13:27:21 +02:00
pydebug.h gh-77782: Deprecate global configuration variable (#93943) 2022-06-17 16:12:00 +02:00
pyerrors.h gh-132449: Improve syntax error messages for keywords with typos (#132450) 2025-04-22 11:01:55 +02:00
pyfpe.h bpo-35134: Move non-limited C API files to Include/cpython/ (GH-24561) 2021-02-19 15:55:46 +01:00
pyframe.h Fix typos in comments (#120188) 2024-06-07 10:19:41 +02:00
pyhash.h gh-111389: replace deprecated occurrences of _PyHASH_* macros (#141236) 2025-11-09 15:14:08 +01:00
pylifecycle.h gh-129033: Remove _Py_InitializeMain() function (#129034) 2025-01-20 10:03:22 +00:00
pylock.h gh-79315: Remove Include/pylock.h and Include/monitoring.h (#139731) 2025-10-08 00:49:24 +02:00
pymem.h gh-90815: Add mimalloc memory allocator (#109914) 2023-10-30 15:43:11 +00:00
pystate.h gh-139653: Add PyUnstable_ThreadState_SetStackProtection() (#139668) 2025-11-13 17:30:50 +01:00
pystats.h gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
pythonrun.h gh-106320: Remove private pythonrun API (#108599) 2023-08-29 04:18:52 +02:00
pythread.h gh-129296: Fix pyatomic.h include paths (#129320) 2025-01-29 15:06:19 +00:00
pytime.h gh-110850: Add PyTime_TimeRaw() function (#118394) 2024-05-01 18:05:01 +00:00
setobject.h gh-112069: Make PySet_GET_SIZE to be atomic safe. (gh-118053) 2024-04-19 06:40:28 +09:00
sliceobject.h gh-79315: Add Include/cpython/sliceobject.h header (#139729) 2025-10-08 00:48:18 +02:00
structseq.h gh-79315: Add Include/cpython/structseq.h header (#139730) 2025-10-08 01:19:50 +02:00
traceback.h gh-106320: Remove private _PyTraceback functions (#108453) 2023-08-24 23:35:47 +00:00
tracemalloc.h Add extern "C" around PyTraceMalloc_ functions. (#127772) 2024-12-11 10:27:07 +01:00
tupleobject.h gh-111489: Add PyTuple_FromArray() function (#139691) 2025-10-10 08:54:12 +02:00
unicodeobject.h gh-92536: Fix comment about number of unicode string types (#136439) 2025-07-08 23:49:55 +02:00
warnings.h gh-139640: Fix swallowing syntax warnings in different modules (GH-139755) 2025-10-14 17:48:09 +03:00
weakrefobject.h gh-133644: remove PyWeakref_GetObject and PyWeakref_GET_OBJECT (GH-133657) 2025-09-24 11:25:56 +02:00