Movatterモバイル変換

github-project-automationbot added this toDocs PRs

github-project-automationbot moved this toTodo inDocs PRs

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

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

Fidget-Spinner reviewed

Copy link

Member

Fidget-Spinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

		@@ -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

Copy link

Member

Fidget-SpinnerMar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Needs a line spacing

Suggested change

	##How to add a new bytecode specialization

	##How to add a new bytecode specialization

InternalDocs/interpreter.md Outdated


		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

Copy link

Member

Fidget-SpinnerMar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

Fidget-Spinner requested a review fromiritkatriel

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

Fidget-Spinner added the skip issue label

faizanoor3001 added2 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

Copy link

Member

iritkatriel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

A few tweak/suggestions

InternalDocs/interpreter.md Outdated

Comment on lines 528 to 529

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

Copy link

Member

iritkatrielMar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change

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

InternalDocs/interpreter.md Outdated

Comment on lines 545 to 546

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

Copy link

Member

iritkatrielMar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Create a macro for the original bytecode name:

macro(CONTAINS_OP)=_SPECIALIZE_CONTAINS_OP+_CONTAINS_OP;

InternalDocs/interpreter.md Outdated

Comment on lines 557 to 565

		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.

Copy link

Member

iritkatrielMar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

Copy link

Member

iritkatrielMar 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

faizanoor3001 added3 commits

March 4, 2025 22:56

Merge branch 'main' ofhttps://github.com/python/cpythoninto 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

Copy link

Member

iritkatriel commentedMar 4, 2025

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

faizanoor3001 added2 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

Copy link

Member

brandtbucher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

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

Copy link

Member

brandtbucherMar 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Nit, presumably this would use both operands:

Suggested change

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

Copy link

Member

brandtbucherMar 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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 callsPyUnicode_Contains or something.

bedevere-appbot added awaiting merge and removed awaiting review labels

Mar 5, 2025

ZeroIntensity reviewed

Mar 6, 2025

Copy link

Member

ZeroIntensity left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Several grammar nitpicks--English is hard!

Comment on lines +511 to +512

		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):

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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):

		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)

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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)

Comment on lines +516 to +518

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

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

		}
		```

		- Create a macro for the original bytecode name:

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

"intruction" reads better to me here.

Suggested change

	- Create a macro for the originalbytecode name:
	- Create a macro for the originalinstruction name:

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

Comment on lines +550 to +551

		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.

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

		} _PyContainsOpCache;
		```

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

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

_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).

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

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

Comment on lines +564 to +565

		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.

Copy link

Member

ZeroIntensityMar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

"to," not "in."
I think the context already implies that it's Python'sdis module :)

Suggested change

	5. Add the cache layoutin[Lib/opcode.py](../Lib/opcode.py) so thatPython's
	`dis` module will know how to represent it properly.
	5. Add the cache layoutto[Lib/opcode.py](../Lib/opcode.py) so thatthe
	`dis` module will know how to represent it properly.