python / python/devguide

Document how to add a bytecode specialization

未关闭
#1,286 11 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

good first issue help wanted
主要语言
Python
星标
2.1k
派生
1k
平均合并
2 天 12 小时
30 天内合并 PR
12

描述

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:

  1. Set the original CONTAINS_OP to a uop by changing it from CONTAINS_OP to _CONTAINS_OP in Python/bytecodes.c. The instruction definition should also change from inst to op.
  2. Add the uop that calls a specializing function. In this case _SPECIALIZE_CONTAINS_OP.
  3. The original CONTAINS_OP is now a new macro consisting of _SPECIALIZE_CONTAINS_OP + _CONTAINS_OP.
  4. Define the cache structure in Include/internal/pycore_code.h. At the very least, a 16-bit counter is needed.
  5. Write the specializing function itself in Python/specialize.c. Refer to any other function in that file for the format.
  6. Remember to update operation stats by calling add_stat_dict in Python/specialize.c.
  7. Add the cache layout in Lib/opcode.py so that Python's dis module will know how to represent it properly.
  8. Bump magic number in Include/internal/pycore_magic_number.h.
  9. Run make regen-all on *nix or build.bat --regen on PC.

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

使用 PR 116385 和九步大纲作为参考材料。首先查看所引用的更改和指定的文件—Python/bytecodes.c、Include/internal/pycore_code.h、Python/specialize.c、Lib/opcode.py 和 Include/internal/pycore_magic_number.h—然后选择 devguide 或 CPython 文档中的合适位置。完成的标准是:新贡献者能够按照 specialization 工作流操作,并使用 make regen-all 或 build.bat --regen 进行验证。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
compilers, documentation
Issue 类型
文档
难度
3/5
预计耗时
1-2 天
活跃度
活跃
描述清晰度
基本清楚
新手友好度
74/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。