4fa80ce74c
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`.
The JIT Compiler
This version of CPython can be built with an experimental just-in-time compiler1 . While most everything you already know about building and using CPython is unchanged, you will probably need to install a compatible version of LLVM first.
Python 3.11 or newer is required to build the JIT.
Installing LLVM
The JIT compiler does not require end users to install any third-party dependencies, but part of it must be built using LLVM2 . You are not required to build the rest of CPython using LLVM, or even the same version of LLVM (in fact, this is uncommon).
LLVM version 21 is the officially supported version. You can modify if needed using the LLVM_VERSION env var during configure. Both clang and llvm-readobj need to be installed and discoverable (version suffixes, like clang-19, are okay). It's highly recommended that you also have llvm-objdump available, since this allows the build script to dump human-readable assembly for the generated code.
It's easy to install all of the required tools:
Linux
Install LLVM 21 on Ubuntu/Debian:
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21
Install LLVM 21 on Fedora Linux 40 or newer:
sudo dnf install 'clang(major) = 21' 'llvm(major) = 21'
macOS
Install LLVM 21 with Homebrew:
brew install llvm@21
Homebrew won't add any of the tools to your $PATH. That's okay; the build script knows how to find them.
Windows
LLVM is downloaded automatically (along with other external binary dependencies) by PCbuild\build.bat.
Otherwise, you can install LLVM 21 by searching for it on LLVM's GitHub releases page, clicking on "Assets", downloading the appropriate Windows installer for your platform (likely the file ending with -win64.exe), and running it. When installing, be sure to select the option labeled "Add LLVM to the system PATH".
Alternatively, you can use chocolatey:
choco install llvm --version=21.1.0
Dev Containers
If you are working on CPython in a Codespaces instance, there's no need to install LLVM as the Fedora 43 base image includes LLVM 21 out of the box.
Building
For PCbuild-based builds, pass the --experimental-jit option to build.bat.
For all other builds, pass the --enable-experimental-jit option to configure.
Otherwise, just configure and build as you normally would. Cross-compiling "just works", since the JIT is built for the host platform.
The JIT can also be enabled or disabled using the PYTHON_JIT environment variable, even on builds where it is enabled or disabled by default. More details about configuring CPython with the JIT and optional values for --enable-experimental-jit can be found here.
Miscellaneous
If you're looking for information on how to update the JIT build dependencies, see JIT Build Infrastructure.
-
Clang is specifically needed because it's the only C compiler with support for guaranteed tail calls (
musttail), which are required by CPython's continuation-passing-style approach to JIT compilation. Since LLVM also includes other functionalities we need (namely, object file parsing and disassembly), it's convenient to only support one toolchain at this time. ↩︎