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.

InternalDocs/interpreter.md

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:

InternalDocs/interpreter.md

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!

InternalDocs/interpreter.md

hugovk · 2025-10-14T08:32:11Z

I've applied the suggestions. Ready to merge? And backport?

Co-authored-by: Ken Jin <[email protected]> Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Brandt Bucher <[email protected]>

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 Documentation in the Doc dir skip news awaiting review labels Mar 4, 2025

github-project-automation bot added this to Docs PRs Mar 4, 2025

github-project-automation bot moved this to Todo in Docs PRs 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

Apply suggestions from code review

947a2d4

Co-authored-by: Ken Jin <[email protected]> Co-authored-by: Peter Bierma <[email protected]> Co-authored-by: Brandt Bucher <[email protected]>

hugovk requested a review from AA-Turner as a code owner October 14, 2025 08:33

	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`.

		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.

Uh oh!

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

Uh oh!

Conversation

faizanoor3001 commented Mar 4, 2025

Solves: python/devguide#1286

Description

Uh oh!

Fidget-Spinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Fidget-Spinner Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

iritkatriel left a comment

Choose a reason for hiding this comment

Uh oh!

iritkatriel Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

iritkatriel Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

iritkatriel Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

iritkatriel Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

iritkatriel commented Mar 4, 2025

Uh oh!

brandtbucher left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brandtbucher Mar 5, 2025

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

hugovk commented Oct 14, 2025 •

edited

Loading