Document how to add a bytecode specialization
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.1k
- Forks
- 1k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 12
Description
How to add a new bytecode specialization is knowledge only a few of us remember right now. We should document this somewhere (devguide or CPython, I don't mind). Hopefully a new contributor can pick this up!
There reference is this PR: https://github.com/python/cpython/pull/116385/files
Assuming you found an instruction that serves as a good specialization candidate. Let's use the example of CONTAINS_OP:
- Set the original
CONTAINS_OPto a uop by changing it fromCONTAINS_OPto_CONTAINS_OPinPython/bytecodes.c. The instruction definition should also change frominsttoop. - Add the uop that calls a specializing function. In this case
_SPECIALIZE_CONTAINS_OP. - The original
CONTAINS_OPis now a new macro consisting of_SPECIALIZE_CONTAINS_OP + _CONTAINS_OP. - Define the cache structure in
Include/internal/pycore_code.h. At the very least, a 16-bit counter is needed. - Write the specializing function itself in
Python/specialize.c. Refer to any other function in that file for the format. - Remember to update operation stats by calling
add_stat_dictinPython/specialize.c. - Add the cache layout in
Lib/opcode.pyso that Python'sdismodule will know how to represent it properly. - Bump magic number in
Include/internal/pycore_magic_number.h. - Run
make regen-allon *nix orbuild.bat --regenon PC.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Use PR 116385 and the nine-step outline as the source material. Start by reviewing the referenced changes and the named files—Python/bytecodes.c, Include/internal/pycore_code.h, Python/specialize.c, Lib/opcode.py, and Include/internal/pycore_magic_number.h—then choose the devguide or CPython documentation location. Done means a newcomer can follow the specialization workflow and verify it with make regen-all or build.bat --regen.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- compilers, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100