Skip to main content

Include/internal/pycore_opcode_metadata.h

cpython 3.14 @ ab2d84fe1023/Include/internal/pycore_opcode_metadata.h

This header is entirely machine-generated by Tools/cases_generator/generate_cases.py from the instruction definitions in Python/bytecodes.c. It must never be edited by hand. Every time a new opcode is added, renamed, or its cache layout changes, the generator is re-run and this file is replaced wholesale.

The file has two concerns. First, it provides bitmask constants (OPCODE_HAS_ARG, OPCODE_HAS_JUMP, and so on) that describe properties a single opcode may exhibit. Second, it provides a family of flat arrays indexed by the raw opcode integer: _PyOpcode_opcode_metadata for name and flags, _PyOpcode_num_popped and _PyOpcode_num_pushed for static stack effects, _PyOpcode_Caches for the number of inline cache words, and _PyOpcode_Deopt for mapping a specialized opcode back to its unspecialized base.

The deopt table is what makes adaptive specialization safe. When a guard fails at runtime the interpreter reads _PyOpcode_Deopt[opcode] to obtain the canonical base opcode, then re-executes using that base without touching the surrounding eval loop structure.

Map​

LinesSymbolRolegopy
1-20OPCODE_HAS_ARG, OPCODE_HAS_JUMP, OPCODE_HAS_EXCVAL, OPCODE_HAS_NAME, OPCODE_HAS_CONST, OPCODE_HAS_FREE, OPCODE_HAS_LOCAL, OPCODE_HAS_EVAL_BREAK, OPCODE_HAS_DEOPT, OPCODE_HAS_ERROR, OPCODE_HAS_ESCAPESBitmask flag constants for opcode propertiesnot ported
21-40struct _PyOpcodeMetadataEntryPer-opcode record: name, valid_entry, flagsnot ported
41-100_PyOpcode_opcode_metadata[]256-entry array of _PyOpcodeMetadataEntry indexed by opcodenot ported
101-130_PyOpcode_num_popped[], _PyOpcode_num_pushed[]Static stack effect counts per opcodenot ported
131-160_PyOpcode_Caches[]Inline cache word count per opcodenot ported
161-195_PyOpcode_Deopt[]Specialized-to-base opcode remapping tablenot ported
196-220OPCODE_HAS_* query macrosInline helpers that AND flags against the metadata arraynot ported

Reading​

Flag constants (lines 1 to 20)​

cpython 3.14 @ ab2d84fe1023/Include/internal/pycore_opcode_metadata.h#L1-20

Each OPCODE_HAS_* constant is a power-of-two bitmask. Callers combine them with bitwise AND against the flags field of _PyOpcodeMetadataEntry to ask questions like "does this opcode consume an argument word?" or "can this opcode raise an exception that needs an exception table lookup?"

#define OPCODE_HAS_ARG          (1 << 0)
#define OPCODE_HAS_JUMP         (1 << 1)
#define OPCODE_HAS_EXCVAL       (1 << 2)
#define OPCODE_HAS_DEOPT        (1 << 8)
#define OPCODE_HAS_ERROR        (1 << 9)

Metadata array (lines 41 to 100)​

cpython 3.14 @ ab2d84fe1023/Include/internal/pycore_opcode_metadata.h#L41-100

_PyOpcode_opcode_metadata is a 256-element C array. Slots for unused opcode values have valid_entry = 0 so callers can detect invalid opcodes without a separate lookup table. The name pointer is a string literal in the read-only segment, useful for tracing and disassembly without importing the dis module.

extern const struct _PyOpcodeMetadataEntry
    _PyOpcode_opcode_metadata[256];

Stack effect tables (lines 101 to 160)​

cpython 3.14 @ ab2d84fe1023/Include/internal/pycore_opcode_metadata.h#L101-160

_PyOpcode_num_popped and _PyOpcode_num_pushed store the static (non-argument-dependent) stack effect for each opcode. The compiler uses these during the stack-depth pass to verify that no path through a code object can underflow the value stack. A value of -1 signals that the effect is dynamic and must be computed separately.

extern const int8_t _PyOpcode_num_popped[256];
extern const int8_t _PyOpcode_num_pushed[256];

Deopt table (lines 161 to 195)​

cpython 3.14 @ ab2d84fe1023/Include/internal/pycore_opcode_metadata.h#L161-195

_PyOpcode_Deopt maps every specialized opcode (e.g., LOAD_ATTR_MODULE) to its canonical base opcode (LOAD_ATTR). For opcodes that are already base opcodes the table is the identity. The eval loop calls into this table on a specialization miss so it can fall back cleanly without duplicating dispatch logic.

extern const uint8_t _PyOpcode_Deopt[256];

gopy mirror​

Not yet ported.