Dec 6, 2024 · Nov 22, 2024 · Nov 22, 2024 · Nov 23, 2024 · Nov 28, 2024 · Dec 5, 2024
diff --git a/InternalDocs/README.md b/InternalDocs/README.md

 - [The Specializing Interpreter](adaptive.md)

 - [The Tier 2 Interpreter (coming soon)](tier2.md)
 - [The Tier 2 Interpreter](tier2.md)

 - [Garbage Collector Design](garbage_collector.md)

diff --git a/InternalDocs/tier2.md b/InternalDocs/tier2.md
 # The Tier 2 Interpreter

 Coming soon.
 The [basic interpreter](interpreter.md), also referred to as the `tier 1`
 interpreter, consists of a main loop that executes the bytecode instructions
 generated by the [bytecode compiler](compiler.md) and their
 [specializations](adaptive.md). Runtime optimization in tier 1 can only be
 done for one instruction at a time. The `tier 2` interpreter is based on a
 mechanism to replace an entire sequence of bytecode instructions, and this
 enables optimizations that span multiple instructions.

 ## The Optimizer and Executors

 The program begins running in tier 1, until a `JUMP_BACKWARD` instruction
 determines that it is `hot` because the counter in its
 [inline cache](interpreter.md#inline-cache-entries) indicates that is
 executed more than some threshold number of times. It then calls the
 function `_PyOptimizer_Optimize()` in
 [`Python/optimizer.c`](../Python/optimizer.c), passing it the current
 [frame](frames.md) and instruction pointer. `_PyOptimizer_Optimize()`
 constructs an object of type
 [`_PyExecutorObject`](Include/internal/pycore_optimizer.h) which implements
 an optimized version of the instruction trace beginning at this jump.

 The optimizer determines where the trace ends, and the executor is set up
 to either return to `tier 1` and resume execution, or transfer control
 to another executor (see `_PyExitData` in Include/internal/pycore_optimizer.h).

 The executor is stored on the [`code object`](code_objects.md) of the frame,
 in the `co_executors` field which is an array of executors. The start
 instruction of the trace (the `JUMP_BACKWARD`) is replaced by an
 `ENTER_EXECUTOR` instruction whose `oparg` is equal to the index of the
 executor in `co_executors`.

 ## The uop optimizer

 The optimizer that `_PyOptimizer_Optimize()` runs is configurable
 via the `_Py_SetTier2Optimizer()` function (this is used in test
 via `_testinternalcapi.set_optimizer()`.)

 The tier 2 optimizer, `_PyUOpOptimizer_Type`, is defined in
 [`Python/optimizer.c`](../Python/optimizer.c). It translates
 an instruction trace into a sequence of micro-ops by replacing
 each bytecode by an equivalent sequence of micro-ops
 (see `_PyOpcode_macro_expansion` in
 [pycore_opcode_metadata.h](../Include/internal/pycore_opcode_metadata.h)
 which is generated from [`Python/bytecodes.c`](../Python/bytecodes.c)).
 The micro-op sequence is then optimized by
 `_Py_uop_analyze_and_optimize` in
 [`Python/optimizer_analysis.c`](../Python/optimizer_analysis.c).

 ## Running a uop executor

 After a tier 1 `JUMP_BACKWARD` instruction invokes the uop optimizer
 to create a tier 2 uop executor, it transfers control to this executor
 via the `GOTO_TIER_TWO` macro, which jumps to `tier2_dispatch:` in
 [`Python/ceval.c`](../Python/ceval.c), where there is a loops that
 executes the micro-ops which are defined in
 [`Python/executor_cases.c.h`](../Python/executor_cases.c.h).
 This loop exits when an `_EXIT_TRACE` or `_DEOPT` uop is reached.

 ## Invalidating Executors

 In addition to being stored on the code object, each executor is also
 inserted into a list of all executors which is stored in the interpreter
 state's `executor_list_head` field. This list is used when it is necessary
 to invalidate executors because values that their construction depended
 on may have changed.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -38,7 +38,7 @@ Program Execution

		- [The Specializing Interpreter](adaptive.md)

		- [The Tier 2 Interpreter (coming soon)](tier2.md)
		- [The Tier 2 Interpreter](tier2.md)

		- [Garbage Collector Design](garbage_collector.md)

Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1,67 @@
		# The Tier 2 Interpreter
Copy link Member markshannonDec 3, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. This is potentially confusing. The tier 2 interpreter is, in my mind, only used to debug tier 2 code. It is the jit-compiled machine code that executes tier 2 normally. Also, I think we want to move away from "tier 2" and use "JIT". Seefaster-cpython/ideas#614 (comment) Copy link MemberAuthor iritkatrielDec 5, 2024 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I'm making this change, but the code does refer to tier 2 in various places so I think it needs to be mentioned, otherwise future devs will be confused.

		Coming soon.
		The [basic interpreter](interpreter.md), also referred to as the `tier 1`
		interpreter, consists of a main loop that executes the bytecode instructions
		generated by the [bytecode compiler](compiler.md) and their
		[specializations](adaptive.md). Runtime optimization in tier 1 can only be
		done for one instruction at a time. The `tier 2` interpreter is based on a
		mechanism to replace an entire sequence of bytecode instructions, and this
		enables optimizations that span multiple instructions.

		## The Optimizer and Executors

		The program begins running in tier 1, until a `JUMP_BACKWARD` instruction
		determines that it is `hot` because the counter in its
iritkatriel marked this conversation as resolved. OutdatedShow resolvedHide resolved
		[inline cache](interpreter.md#inline-cache-entries) indicates that is
		executed more than some threshold number of times. It then calls the
iritkatriel marked this conversation as resolved. OutdatedShow resolvedHide resolved
		function `_PyOptimizer_Optimize()` in
		[`Python/optimizer.c`](../Python/optimizer.c), passing it the current
		[frame](frames.md) and instruction pointer. `_PyOptimizer_Optimize()`
		constructs an object of type
		[`_PyExecutorObject`](Include/internal/pycore_optimizer.h) which implements
		an optimized version of the instruction trace beginning at this jump.

		The optimizer determines where the trace ends, and the executor is set up
		to either return to `tier 1` and resume execution, or transfer control
		to another executor (see `_PyExitData` in Include/internal/pycore_optimizer.h).

		The executor is stored on the [`code object`](code_objects.md) of the frame,
		in the `co_executors` field which is an array of executors. The start
		instruction of the trace (the `JUMP_BACKWARD`) is replaced by an
		`ENTER_EXECUTOR` instruction whose `oparg` is equal to the index of the
		executor in `co_executors`.

		## The uop optimizer
iritkatriel marked this conversation as resolved. OutdatedShow resolvedHide resolved

		The optimizer that `_PyOptimizer_Optimize()` runs is configurable
		via the `_Py_SetTier2Optimizer()` function (this is used in test
		via `_testinternalcapi.set_optimizer()`.)
iritkatriel marked this conversation as resolved. OutdatedShow resolvedHide resolved

		The tier 2 optimizer, `_PyUOpOptimizer_Type`, is defined in
		[`Python/optimizer.c`](../Python/optimizer.c). It translates
		an instruction trace into a sequence of micro-ops by replacing
		each bytecode by an equivalent sequence of micro-ops
		(see `_PyOpcode_macro_expansion` in
		[pycore_opcode_metadata.h](../Include/internal/pycore_opcode_metadata.h)
		which is generated from [`Python/bytecodes.c`](../Python/bytecodes.c)).
		The micro-op sequence is then optimized by
		`_Py_uop_analyze_and_optimize` in
		[`Python/optimizer_analysis.c`](../Python/optimizer_analysis.c).

		## Running a uop executor

		After a tier 1 `JUMP_BACKWARD` instruction invokes the uop optimizer
		to create a tier 2 uop executor, it transfers control to this executor
		via the `GOTO_TIER_TWO` macro, which jumps to `tier2_dispatch:` in
		[`Python/ceval.c`](../Python/ceval.c), where there is a loops that
iritkatriel marked this conversation as resolved. OutdatedShow resolvedHide resolved
		executes the micro-ops which are defined in
		[`Python/executor_cases.c.h`](../Python/executor_cases.c.h).
		This loop exits when an `_EXIT_TRACE` or `_DEOPT` uop is reached.
iritkatriel marked this conversation as resolved. OutdatedShow resolvedHide resolved

		## Invalidating Executors

		In addition to being stored on the code object, each executor is also
		inserted into a list of all executors which is stored in the interpreter
		state's `executor_list_head` field. This list is used when it is necessary
		to invalidate executors because values that their construction depended
		on may have changed.