Document how to add a bytecode specialization in Interpreter.md file #130831

faizanoor3001 · 2025-03-04T12:42:13Z

Solves: python/devguide#1286

Description

Add a "How to Add a New Bytecode Specialization” section in the InternalDocs/interpreter.md file.
- This guide explains how to add a new bytecode specialization, using
  CONTAINS_OP as an example.

PS: Initial PR for reference: python/devguide#1522

📚 Documentation preview 📚: https://cpython-devguide--1522.org.readthedocs.build/

…lization steps

…ecode-specialization-guide

Fidget-Spinner

Thanks. Look good mostly. Just a few minor edits.

Fidget-Spinner · 2025-03-04T13:52:07Z

InternalDocs/interpreter.md

@@ -505,6 +505,62 @@ After the last `DEOPT_IF` has passed, a hit should be recorded with
 `STAT_INC(BASE_INSTRUCTION, hit)`.
 After an optimization has been deferred in the adaptive instruction,
 that should be recorded with `STAT_INC(BASE_INSTRUCTION, deferred)`.
+## How to add a new bytecode specialization


Needs a line spacing

Suggested change

## How to add a new bytecode specialization

## How to add a new bytecode specialization

Fidget-Spinner · 2025-03-04T13:52:59Z

InternalDocs/interpreter.md

+
+3. Write the specializing function itself in [Python/specialize.c ](../Python/specialize.c). 
+   Refer to any other function in that file for the format.
+4. Remember to update operation stats by calling add_stat_dict in 


Suggested change

4. Remember to update operation stats by calling add_stat_dict in

4. Remember to update operation stats by calling `add_stat_dict` in

…lization-guide

iritkatriel

A few tweak/suggestions

iritkatriel · 2025-03-04T20:18:56Z

InternalDocs/interpreter.md

+- Add a uop that calls the specializing function `_SPECIALIZE_CONTAINS_OP`. 
+  For example.


Suggested change

- Add a uop that calls the specializing function `_SPECIALIZE_CONTAINS_OP`.

For example.

- Add a uop that calls the specializing function:

iritkatriel · 2025-03-04T20:22:00Z

InternalDocs/interpreter.md

+- The original `CONTAINS_OP` is now a new macro consisting of
+      `_SPECIALIZE_CONTAINS_OP` and `_CONTAINS_OP`.


Create a macro for the original bytecode name:

macro(CONTAINS_OP) = _SPECIALIZE_CONTAINS_OP + _CONTAINS_OP;

iritkatriel · 2025-03-04T20:26:26Z

InternalDocs/interpreter.md

+3. Write the specializing function itself in [Python/specialize.c ](../Python/specialize.c). 
+   Refer to any other function in that file for the format.
+4. Remember to update operation stats by calling `add_stat_dict` in 
+   [Python/specialize.c ](../Python/specialize.c).
+5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's 
+   dis module will know how to represent it properly.
+6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
+7. Run ``make regen-all`` on `*nix` or `build.bat --regen` on Windows.
+


Suggested change

3. Write the specializing function itself in [Python/specialize.c ](../Python/specialize.c).

Refer to any other function in that file for the format.

4. Remember to update operation stats by calling `add_stat_dict` in

[Python/specialize.c ](../Python/specialize.c).

5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's

dis module will know how to represent it properly.

6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).

7. Run ``make regen-all`` on `*nix` or `build.bat --regen` on Windows.

3. Write the specializing function itself (_Py_Specialize_ContainsOp) in [Python/specialize.c ](../Python/specialize.c).

Refer to other functions in that file for the pattern.

4. Add a call to `add_stat_dict` in `_Py_GetSpecializationStats` which is in

[Python/specialize.c ](../Python/specialize.c).

5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's

`dis` module will know how to represent it properly.

6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).

7. Run `make regen-all` on `*nix` or `build.bat --regen` on Windows.

This suggestion has some edits to the text as well, not just whitespace.

…ecode-specialization-guide

iritkatriel · 2025-03-04T21:24:12Z

Let's give @brandtbucher a chance to review as well.

…lization-guide

brandtbucher

Looks correct. A couple of possible minor improvements, if we're aiming to be comprehensive here:

brandtbucher · 2025-03-05T23:55:13Z

InternalDocs/interpreter.md

+            #if ENABLE_SPECIALIZATION
+            if (ADAPTIVE_COUNTER_IS_ZERO(counter)) {
+                next_instr = this_instr;
+                _Py_Specialize_ContainsOp(right, next_instr);


Nit, presumably this would use both operands:

Suggested change

_Py_Specialize_ContainsOp(right, next_instr);

_Py_Specialize_ContainsOp(left, right, next_instr);

brandtbucher · 2025-03-05T23:58:10Z

InternalDocs/interpreter.md

+6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
+
+7. Run ``make regen-all`` on `*nix` or `build.bat --regen` on Windows.
+


Seems like the only thing missing is adding an actual specialized variant. Maybe that's implied/obvious, but it wouldn't hurt to provide a dumb example of _Py_Specialize_ContainsOp and _CONTAINS_OP_UNICODE_UNICODE that just guards and calls PyUnicode_Contains or something.

ZeroIntensity

Several grammar nitpicks--English is hard!

ZeroIntensity · 2025-03-06T11:08:31Z

InternalDocs/interpreter.md

+Assuming you found an instruction that serves as a good specialization candidate. 
+Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):


This sentence is a dependent clause, you either need a comma and then some more information, or remove the word "assuming." How about this?

Suggested change

Assuming you found an instruction that serves as a good specialization candidate.

Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):

Let's say you found an instruction that serves as a good specialization candidate, such as [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):

ZeroIntensity · 2025-03-06T11:10:06Z

InternalDocs/interpreter.md

+Assuming you found an instruction that serves as a good specialization candidate. 
+Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
+
+1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)


I don't really like the phrase "Update below in," it's kind of wordy and an incomplete sentence. You could try something like this:

Suggested change

1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)

1. Make necessary changes to the instruction in [Python/bytecodes.c](../Python/bytecodes.c)

ZeroIntensity · 2025-03-06T11:14:15Z

InternalDocs/interpreter.md

+- Convert `CONTAINS_OP` to a micro-operation (uop) by renaming
+     it to `_CONTAINS_OP` and changing the instruction definition
+     from `inst` to `op`.


CONTAINS_OP is still an example here, we should try to be more general.

For clarity, we could explain why it's a "u."

Reduce indentation.

Suggested change

- Convert `CONTAINS_OP` to a micro-operation (uop) by renaming

it to `_CONTAINS_OP` and changing the instruction definition

from `inst` to `op`.

- Convert the instruction (`CONTAINS_OP`, in our example) to a micro-operation (uop, formally μop) by renaming it to `_INSTRUCTION_NAME` (e.g., `_CONTAINS_OP`) and changing the instruction definition

from `inst` to `op`.

ZeroIntensity · 2025-03-06T11:15:10Z

InternalDocs/interpreter.md

+        }
+  ```
+
+- Create a macro for the original bytecode name:


"intruction" reads better to me here.

Suggested change

- Create a macro for the original bytecode name:

- Create a macro for the original instruction name:

It also might be worth mentioning here what should go in that macro, but it also seems pretty clear based on the example.

ZeroIntensity · 2025-03-06T11:18:31Z

InternalDocs/interpreter.md

+2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),
+at the very least, a 16-bit counter is needed.


The clause after the first comma is independent, so it can't be used there. Let's just turn it into its own sentence.

Suggested change

2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),

at the very least, a 16-bit counter is needed.

2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h). It needs to have at least a 16-bit counter field.

ZeroIntensity · 2025-03-06T11:20:25Z

InternalDocs/interpreter.md

+        } _PyContainsOpCache;
+    ```      
+
+3. Write the specializing function itself (`_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c). 


_Py_Specialize_ContainsOp is an example.

Suggested change

3. Write the specializing function itself (`_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c).

3. Write the specializing function itself (e.g., `_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c).

ZeroIntensity · 2025-03-06T11:20:44Z

InternalDocs/interpreter.md

+3. Write the specializing function itself (`_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c). 
+Refer to other functions in that file for the pattern.
+
+4. Add a call to `add_stat_dict` in  `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).


Extra space.

Suggested change

4. Add a call to `add_stat_dict` in `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).

4. Add a call to `add_stat_dict` in `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).

ZeroIntensity · 2025-03-06T11:23:42Z

InternalDocs/interpreter.md

+5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's 
+   `dis` module will know how to represent it properly.


"to," not "in."

I think the context already implies that it's Python's dis module :)

Suggested change

5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's

`dis` module will know how to represent it properly.

5. Add the cache layout to [Lib/opcode.py](../Lib/opcode.py) so that the

`dis` module will know how to represent it properly.

ZeroIntensity · 2025-03-06T11:23:53Z

InternalDocs/interpreter.md

+5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's 
+   `dis` module will know how to represent it properly.
+
+6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).


Extra space.

Suggested change

6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).

6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).

faizanoor3001 added 2 commits March 4, 2025 13:31

Updated the interpreters.md with the how to add a new bytecode specia…

3bf2baf

…lization steps

Merge branch 'main' of https://github.com/python/cpython into add-byt…

2d2c7e4

…ecode-specialization-guide

bedevere-app bot added docs skip news awaiting review labels Mar 4, 2025

faizanoor3001 changed the title ~~gh-1286 : Document how to add a bytecode specialization in Interpreter.md file~~ python/devguide#1286 : Document how to add a bytecode specialization in Interpreter.md file Mar 4, 2025

faizanoor3001 changed the title ~~python/devguide#1286 : Document how to add a bytecode specialization in Interpreter.md file~~ gh-1286 : Document how to add a bytecode specialization in Interpreter.md file Mar 4, 2025

Fidget-Spinner reviewed Mar 4, 2025

View reviewed changes

Fidget-Spinner requested a review from iritkatriel March 4, 2025 13:53

Fidget-Spinner changed the title ~~gh-1286 : Document how to add a bytecode specialization in Interpreter.md file~~ Document how to add a bytecode specialization in Interpreter.md file Mar 4, 2025

Fidget-Spinner added the skip issue label Mar 4, 2025

faizanoor3001 added 2 commits March 4, 2025 21:54

Merge remote-tracking branch 'upstream/main' into add-bytecode-specia…

9ec70df

…lization-guide

Addressed the review comments

a023a52

iritkatriel reviewed Mar 4, 2025

View reviewed changes

faizanoor3001 added 3 commits March 4, 2025 22:56

Merge branch 'main' of https://github.com/python/cpython into add-byt…

10a7144

…ecode-specialization-guide

Update section for Step1, reworded as per review comments for clarity

cb03b20

Added new lines between steps for better readability

d9783ca

faizanoor3001 added 2 commits March 4, 2025 23:40

Updated the text for the steps 3,4,5 as per comment

852cbaf

Merge remote-tracking branch 'upstream/main' into add-bytecode-specia…

50ea367

…lization-guide

brandtbucher approved these changes Mar 5, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Mar 5, 2025

ZeroIntensity reviewed Mar 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document how to add a bytecode specialization in Interpreter.md file #130831

Document how to add a bytecode specialization in Interpreter.md file #130831

faizanoor3001 commented Mar 4, 2025

Fidget-Spinner left a comment

Fidget-Spinner Mar 4, 2025

Fidget-Spinner Mar 4, 2025

iritkatriel left a comment

iritkatriel Mar 4, 2025

iritkatriel Mar 4, 2025

iritkatriel Mar 4, 2025

iritkatriel Mar 4, 2025

iritkatriel commented Mar 4, 2025

brandtbucher left a comment

brandtbucher Mar 5, 2025

brandtbucher Mar 5, 2025

ZeroIntensity left a comment

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

ZeroIntensity Mar 6, 2025

	## How to add a new bytecode specialization

	## How to add a new bytecode specialization

	4. Remember to update operation stats by calling add_stat_dict in
	4. Remember to update operation stats by calling `add_stat_dict` in

		- Add a uop that calls the specializing function `_SPECIALIZE_CONTAINS_OP`.
		For example.

		- The original `CONTAINS_OP` is now a new macro consisting of
		`_SPECIALIZE_CONTAINS_OP` and `_CONTAINS_OP`.

	_Py_Specialize_ContainsOp(right, next_instr);
	_Py_Specialize_ContainsOp(left, right, next_instr);

		6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).

		7. Run ``make regen-all`` on `*nix` or `build.bat --regen` on Windows.

		Assuming you found an instruction that serves as a good specialization candidate.
		Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):

	Assuming you found an instruction that serves as a good specialization candidate.
	Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
	Let's say you found an instruction that serves as a good specialization candidate, such as [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):

	1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)
	1. Make necessary changes to the instruction in [Python/bytecodes.c](../Python/bytecodes.c)

	- Create a macro for the original bytecode name:
	- Create a macro for the original instruction name:

		2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),
		at the very least, a 16-bit counter is needed.

	3. Write the specializing function itself (`_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c).
	3. Write the specializing function itself (e.g., `_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c).

	4. Add a call to `add_stat_dict` in `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).
	4. Add a call to `add_stat_dict` in `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).

		5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's
		`dis` module will know how to represent it properly.

Document how to add a bytecode specialization in Interpreter.md file #130831

Are you sure you want to change the base?

Document how to add a bytecode specialization in Interpreter.md file #130831

Conversation

faizanoor3001 commented Mar 4, 2025

Solves: python/devguide#1286

Description

Fidget-Spinner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iritkatriel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iritkatriel commented Mar 4, 2025

brandtbucher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ZeroIntensity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment