cpython/Python
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
..
clinic gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
frozen_modules gh-97669: Create Tools/build/ directory (#97963) 2022-10-17 12:01:00 +02:00
_contextvars.c gh-128384: Use a context variable for warnings.catch_warnings (gh-130010) 2025-04-09 16:18:54 -07:00
_warnings.c gh-135801: Improve filtering by module in warn_explicit() without module argument (GH-140151) 2025-10-30 15:55:39 +02:00
asdl.c bpo-43244: Remove ast.h, asdl.h, Python-ast.h headers (GH-24933) 2021-03-23 20:47:40 +01:00
asm_trampoline.S gh-136459: Add perf trampoline support for macOS (#136461) 2025-07-22 16:47:24 +01:00
assemble.c gh-87859: Track Code Object Local Kinds For Arguments (gh-132980) 2025-04-29 02:21:47 +00:00
ast.c gh-132661: Implement PEP 750 (#132662) 2025-04-30 11:46:41 +02:00
ast_preprocess.c gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
ast_unparse.c gh-132661: Disallow Template/str concatenation after PEP 750 spec update (#135996) 2025-07-21 08:44:26 +02:00
bltinmodule.c gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
bootstrap_hash.c GH-131238: Core header refactor (GH-131250) 2025-03-17 09:19:04 +00:00
brc.c Fix typos in documentation and comments (#119763) 2024-06-04 10:22:22 +00:00
bytecodes.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
ceval.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
ceval_gil.c gh-138050: [WIP] JIT - Streamline MAKE_WARM - move coldness check to executor creation (GH-138240) 2025-10-27 16:37:37 +00:00
ceval_macros.h gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
codecs.c Python/codecs.c: Remove unused forward declaration (#139511) 2025-10-03 13:33:49 +02:00
codegen.c gh-138349: Fix crash when combining module-level annotation and listcomp (#138363) 2025-09-10 15:18:39 +02:00
compile.c gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
condvar.h gh-104530: Enable native Win32 condition variables by default (GH-104531) 2024-02-02 13:50:51 +00:00
config_common.h gh-76785: Add PyInterpreterConfig Helpers (gh-117170) 2024-04-02 20:35:52 +00:00
context.c gh-138192: Fix Context initialization so that all subinterpreters are assigned the MISSING value. (gh-138503) 2025-09-04 17:19:30 +00:00
critical_section.c gh-133296: Publicly expose critical section API that accepts PyMutex (gh-135899) 2025-07-21 17:25:43 -04:00
crossinterp.c gh-140306: Fix memory leaks in cross-interpreter data handling (GH-140307) 2025-10-19 22:24:28 +03:00
crossinterp_data_lookup.h gh-135443: Sometimes Fall Back to __main__.__dict__ For Globals (gh-135491) 2025-06-16 17:34:19 -06:00
crossinterp_exceptions.h gh-132775: Clean Up Cross-Interpreter Error Handling (gh-135369) 2025-06-13 16:45:21 -06:00
dtoa.c gh-131238: Add explicit includes to pycore headers (#131257) 2025-03-17 12:32:43 +01:00
dup2.c gh-108765: Python.h no longer includes <unistd.h> (#108783) 2023-09-02 16:50:18 +02:00
dynamic_annotations.c bpo-32241: Add the const qualifire to declarations of umodifiable strings. (#4748) 2017-12-12 13:55:04 +02:00
dynload_hpux.c gh-88402: Add new sysconfig variables on Windows (GH-110049) 2023-10-04 22:50:29 +00:00
dynload_shlib.c gh-131238: Remove more includes from pycore_interp.h (#131480) 2025-03-19 23:01:32 +01:00
dynload_stub.c gh-88402: Add new sysconfig variables on Windows (GH-110049) 2023-10-04 22:50:29 +00:00
dynload_win.c gh-131942: Use the Python-specific Py_DEBUG macro rather than _DEBUG in Windows-related C code (GH-131944) 2025-05-08 15:01:25 +00:00
emscripten_signal.c GH-108614: Unbreak emscripten build (GH-109132) 2023-09-08 17:54:45 +01:00
emscripten_syscalls.c gh-124621: Emscripten: Fix __syscall_ioctl patch (GH-136993) 2025-07-22 15:05:26 +02:00
emscripten_trampoline.c gh-128627: Use __builtin_wasm_test_function_pointer_signature for Emscripten trampoline (#137470) 2025-09-17 15:33:55 +01:00
emscripten_trampoline_inner.c gh-128627: Use __builtin_wasm_test_function_pointer_signature for Emscripten trampoline (#137470) 2025-09-17 15:33:55 +01:00
errors.c gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
executor_cases.c.h gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
fileutils.c gh-55531: Implement normalize_encoding in C (#136643) 2025-10-30 15:31:47 +01:00
flowgraph.c gh-138714: Don't assume next block has instructions when propagating line numbers (#138770) 2025-09-17 09:52:56 -07:00
frame.c gh-131173: Improve exception handling during take_ownership processing (#132620) 2025-04-17 13:38:34 -07:00
frozen.c GH-89435: os.path should not be a frozen module (#126924) 2024-11-22 18:50:30 +00:00
frozenmain.c Use PyConfig_Get() in frozenmain.c (#137421) 2025-08-06 14:33:28 +02:00
future.c gh-126139: Improve error message location for future statement with unknown feature (#126140) 2024-10-29 23:57:59 +00:00
gc.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
gc_free_threading.c GH-141212: Fix possible memory leak in gc_mark_span_push (gh-141213) 2025-11-10 11:19:13 -05:00
gc_gil.c gh-100240: Use a consistent implementation for freelists (#121934) 2024-07-22 12:08:27 -04:00
generated_cases.c.h gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
getargs.c Revert "gh-112068: C API: Add support of nullable arguments in PyArg_Parse (GH-121303)" (#136991) 2025-07-22 16:39:50 +03:00
getcompiler.c gh-141341: Rename COMPILER macro to _Py_COMPILER on Windows (#141342) 2025-11-10 15:50:51 +01:00
getcopyright.c gh-126133: Only use start year in PSF copyright, remove end years (#126236) 2024-11-12 15:59:19 +02:00
getopt.c GH-133336: Remove reserved `-J` flag for Jython (#133444) 2025-05-05 15:09:19 +00:00
getplatform.c bpo-32150: Expand tabs to spaces in C files. (#4583) 2017-11-28 17:56:10 +02:00
getversion.c gh-119132: Remove "experimental" tag from the CPython free-threading. (gh-135550) 2025-06-16 23:32:52 +09:00
hamt.c gh-137440: Update comment in Python/hamt.c on importing for testing (GH-137441) 2025-08-07 09:50:49 -04:00
hashtable.c gh-111545: Add Py_HashPointer() function (#112096) 2023-12-06 15:09:22 +01:00
import.c gh-141376: Fix exported symbols (GH-141377) 2025-11-11 09:21:24 +01:00
importdl.c gh-141169: Re-raise exception from findfuncptr (GH-141349) 2025-11-11 13:52:13 +01:00
index_pool.c gh-91048: Refactor and optimize remote debugging module (#134652) 2025-05-25 20:19:29 +00:00
initconfig.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
instruction_sequence.c GH-124715: Move trashcan mechanism into Py_Dealloc (GH-132280) 2025-04-30 11:37:53 +01:00
instrumentation.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
interpconfig.c GH-131238: Core header refactor (GH-131250) 2025-03-17 09:19:04 +00:00
intrinsics.c gh-111489: Remove _PyTuple_FromArray() alias (#139973) 2025-10-11 22:58:14 +02:00
jit.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
legacy_tracing.c gh-137400: Fix thread-safety issues when profiling all threads (gh-137518) 2025-08-13 14:15:12 -04:00
lock.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
marshal.c gh-140061: Use _PyObject_IsUniquelyReferenced() to check if objects are uniquely referenced (gh-140062) 2025-10-15 09:48:21 -04:00
modsupport.c gh-137210: Add a struct, slot & function for checking an extension's ABI (GH-137212) 2025-09-05 16:23:18 +02:00
mysnprintf.c Add a warning message about PyOS_snprintf (#95993) 2022-10-07 11:49:53 -07:00
mystrtoul.c gh-108765: Python.h no longer includes <ctype.h> (#108831) 2023-09-03 18:54:27 +02:00
object_stack.c gh-100240: Use a consistent implementation for freelists (#121934) 2024-07-22 12:08:27 -04:00
opcode_targets.h gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
optimizer.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
optimizer_analysis.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
optimizer_bytecodes.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
optimizer_cases.c.h gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
optimizer_symbols.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
parking_lot.c gh-137433: Fix deadlock with stop-the-world and daemon threads (gh-137735) 2025-09-16 09:21:58 +01:00
pathconfig.c gh-133644: Remove deprecated Python initialization getter functions (#133661) 2025-05-09 11:39:23 +00:00
perf_jit_trampoline.c gh-136459: Use platform-specific type in perf_jit_trampoline (GH-137031) 2025-07-23 10:20:42 +02:00
perf_trampoline.c gh-137291: Support perf profiler with an evaluation hook (#137292) 2025-08-07 14:54:12 -07:00
preconfig.c GH-133711: Enable UTF-8 mode by default (PEP 686) (#133712) 2025-07-15 10:45:41 +01:00
pyarena.c Chore: Fix typo in pyarena.c (#126527) 2024-11-07 16:37:41 +01:00
pyctype.c
pyfpe.c bpo-46315: Add ifdef HAVE_ feature checks for WASI compatibility (GH-30507) 2022-01-13 09:46:04 +01:00
pyhash.c gh-111389: replace deprecated occurrences of _PyHASH_* macros (#141236) 2025-11-09 15:14:08 +01:00
pylifecycle.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
pymath.c bpo-45440: Remove pymath.c fallbacks (GH-28977) 2021-10-15 19:45:34 +02:00
pystate.c gh-139109: A new tracing JIT compiler frontend for CPython (GH-140310) 2025-11-13 18:08:32 +00:00
pystats.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
pystrcmp.c gh-108767: Replace ctype.h functions with pyctype.h functions (#108772) 2023-09-01 18:36:53 +02:00
pystrhex.c gh-108765: pystrhex: Replace stdlib.h abs() with Py_ABS() (#108830) 2023-09-02 23:15:54 +02:00
pystrtod.c gh-141004: soft-deprecate Py_INFINITY macro (#141033) 2025-11-12 13:44:49 +01:00
Python-ast.c gh-140471: Fix buffer overflow in AST node initialization with malformed _fields (#140506) 2025-10-23 15:35:21 +00:00
Python-tokenize.c gh-111178: Fix function signatures for test_types (#131455) 2025-03-19 13:46:17 +00:00
pythonrun.c gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
pytime.c Remove internal _PyTime_AsLong() function (#141053) 2025-11-05 18:37:06 +01:00
qsbr.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
README Issue #18093: Factor out the programs that embed the runtime 2014-07-25 21:52:14 +10:00
remote_debug.h gh-139275: Fix compilation of Modules/_remote_debugging_module.c when the system doesn't have process_vm_readv (#139307) 2025-09-25 00:16:44 +01:00
remote_debugging.c Fix compiler warnings in remote debugging (#141060) 2025-11-05 20:18:45 +01:00
specialize.c gh-131253: free-threaded build support for pystats (gh-137189) 2025-11-03 11:36:37 -08:00
stackrefs.c gh-131527: Stackref debug borrow checker (#140599) 2025-11-05 11:12:56 -08:00
stdlib_module_names.h gh-81313: Add the math.integer module (PEP-791) (GH-133909) 2025-10-31 16:13:43 +02:00
structmember.c gh-132685: fix thread safety of PyMember_GetOne with _Py_T_OBJECT (#132690) 2025-04-18 21:03:42 +05:30
suggestions.c GH-131238: Core header refactor (GH-131250) 2025-03-17 09:19:04 +00:00
symtable.c gh-135801: Add the module parameter to compile() etc (GH-139652) 2025-11-13 13:21:32 +02:00
sysmodule.c gh-111389: replace deprecated occurrences of _PyHASH_* macros (#141236) 2025-11-09 15:14:08 +01:00
thread.c gh-134745: Use "pymutex" for sys.thread_info on Windows (#141140) 2025-11-06 16:10:39 +01:00
thread_nt.h gh-134745: Change PyThread_allocate_lock() implementation to PyMutex (#134747) 2025-05-30 10:15:47 +00:00
thread_pthread.h gh-137884: Added threading.get_native_id() on Illumos/Solaris (GH-137927) 2025-08-20 17:10:44 +00:00
thread_pthread_stubs.h gh-125161: return non zero value in pthread_self on wasi (#125303) 2024-10-13 20:59:41 +05:30
tier2_engine.md Docs: fix spelling of the word 'transferring' (#116641) 2024-03-13 23:53:32 +01:00
traceback.c gh-140815: Fix faulthandler for invalid/freed frame (#140921) 2025-11-04 11:48:28 +01:00
tracemalloc.c Fix typo in tracemalloc.c (#139450) 2025-10-01 08:58:18 +02:00
uniqueid.c gh-128923: Use zero to indicate unassigned unique id (#128925) 2025-01-17 16:42:27 +01:00
vm-state.md gh-133079: Remove Py_C_RECURSION_LIMIT & PyThreadState.c_recursion_remaining (GH-133080) 2025-04-29 12:56:20 +02:00

Miscellaneous source files for the main Python shared library