This page defines codebase-specific terms, jargon, and domain concepts used throughout the CPython source tree, providing a technical reference for onboarding engineers.
CPython utilizes a multi-tier execution architecture to optimize performance dynamically by moving from generic bytecode to specialized and optimized machine code.
| Term | Definition |
|---|---|
| Tier 1 | The standard bytecode interpreter. It includes the "quickening" mechanism where generic opcodes are replaced with specialized versions. Implementation resides in Python/ceval.c1-5 and generated instructions are in Python/generated_cases.c.h18-20 |
| Tier 2 | A higher-performance execution tier that operates on Uops (Micro-operations). It involves trace-based optimization and can lead to JIT compilation. Implementation found in Python/optimizer.c1 and generated Uop cases in Python/executor_cases.c.h1-10 |
| Specialization | The process of replacing a generic instruction (e.g., BINARY_OP) with one tailored for specific types (e.g., BINARY_OP_ADD_FLOAT) based on runtime feedback. Logic is triggered in Python/generated_cases.c.h45-51 via _Py_Specialize_BinaryOp. |
| Quickening | A Tier 1 optimization where the interpreter identifies "hot" instructions and prepares them for specialization by allocating inline caches. See _Py_Specialize_Resume in Python/bytecodes.c175-177 |
| JIT Compiler | A Just-In-Time compiler that translates Tier 2 Uop traces into machine code using a stencil-based approach. It uses LLVM-generated code templates to emit machine instructions. Reference Python/jit.c1 |
The following diagram illustrates the lifecycle of code as it moves from generic bytecode to optimized Tier 2 executors.
Sources: Python/bytecodes.c148-180 Python/generated_cases.c.h21-55 Python/optimizer_bytecodes.c93-110 Lib/test/test_capi/test_opt.py118-125
PyThreadState (tstate): Represents a single thread of execution. It holds recursion limits, thread-local exception state, and the eval_breaker. Access via _PyThreadState_GET() in Objects/typeobject.c20_PyInterpreterFrame: A stack frame in the Tier 1 interpreter. It contains the code object being executed, the stack pointer, and local variables. Reference Python/bytecodes.c87-94eval_breaker: A thread-safe atomic variable used to signal that the interpreter loop should drop out to handle signals, GIL release, or instrumentation updates. Checked in Python/bytecodes.c189 and Python/executor_cases.c.h111-114_PyStackRef: A container for object references on the evaluation stack that abstracts away the difference between "owned" and "borrowed" references, particularly important for Tier 2 and JIT. Used extensively in Python/generated_cases.c.h32-37 and Python/bytecodes.c34Parking Lot: A synchronization mechanism used in free-threading to manage threads waiting on locks. Reference Python/pystate.c1_PyExecutorObject): A compiled or optimized sequence of Uops that can be executed as a single unit. It represents a "hot path" or "trace". See Python/bytecodes.c82JitOptContext (ctx): The context used during the optimization of Uops, holding the abstract state of the stack and locals to allow for constant folding and type inference. Used in Python/optimizer_bytecodes.c84-88JitOptSymbol (sym): Represents a symbolic value during Tier 2 optimization, allowing the compiler to track types and constants without executing code. See sym_new_not_null in Python/optimizer_bytecodes.c20Sources: Python/bytecodes.c82-94 Python/ceval.c9-25 Python/optimizer_bytecodes.c1-55 Include/internal/pycore_uop_ids.h1-13 Include/internal/pycore_stackref.h1-10
PyObject: The base structure for all Python objects. In the free-threading build, this includes an ob_mutex for per-object locking. Objects/typeobject.c83None). Their reference counts are handled specially. Checked via sym_is_immortal in Python/optimizer_bytecodes.c98read_u16(&this_instr[1].cache) in Python/generated_cases.c.h42Sources: Python/generated_cases.c.h32-90 Python/optimizer_cases.c.h90-95 Objects/typeobject.c46-57 Python/optimizer_bytecodes.c96-102 Python/gc.c1
| Term | Definition |
|---|---|
| PEG Parser | The parser that transforms Python source into an Abstract Syntax Tree (AST). Defined in Grammar/python.gram. |
| ASDL | Abstract Service Definition Language, used to define the AST structure in Parser/Python.asdl. |
| CFG (Control Flow Graph) | An intermediate representation of code used during compilation to perform optimizations like dead code elimination. Reference Include/internal/pycore_code.h1 |
| Clinic | The "Argument Clinic" tool that parses DSL comments in C files to generate boilerplate argument parsing code. See Objects/typeobject.c34-40 |
| Cases Generator | A toolchain (Tools/cases_generator/) that reads Python/bytecodes.c to generate the interpreter loop and metadata headers. Python/bytecodes.c1-7 |
| Stable ABI / Limited API | A subset of the C API that provides binary compatibility across Python versions. Defined in Doc/data/stable_abi.dat. |
Sources: Objects/typeobject.c1-30 Python/bytecodes.c34 Parser/python.gram1
JUMP_TO_PREDICTED in Python/generated_cases.c.h123_GUARD_TOS_INT). Reference Python/optimizer_bytecodes.c208-210.pyc files are compatible with the running interpreter. See Include/internal/pycore_magic_number.h1cpython-316-x86_64-linux-gnu.so). See Makefile.pre.in42Py_GIL_DISABLED checks in Python/bytecodes.c181-187Sources: Objects/typeobject.c34-40 Python/optimizer_bytecodes.c208-210 Include/internal/pycore_uop_ids.h1-13 Python/generated_cases.c.h99-125 Include/internal/pycore_magic_number.h1 Makefile.pre.in42-51
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.