Skip to main content

Include/internal/pycore_optimizer.h

Source:

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

pycore_optimizer.h defines the API for CPython 3.12+ tier-2 optimizers. The default optimizer (since 3.13) is a copy-and-patch JIT; the interface allows plugging in alternative optimizers.

Map​

LinesSymbolRole
1-50_PyUOpInstructionA micro-op (uop): opcode, operand, target
51-100_PyExecutorObjectA compiled trace: array of uops + metadata
101-140_PyOptimizerObjectOptimizer vtable: optimize, resume_threshold
141-170_PyOptimizer_NewUOpOptimizerCreate the default uop optimizer
171-200_PyOptimizer_OptimizeEntry point: attempt to optimize a trace

Reading​

_PyUOpInstruction​

// CPython: Include/internal/pycore_optimizer.h:28 _PyUOpInstruction
typedef struct {
    uint32_t opcode : 16;
    uint32_t operand0 : 16;
    uint32_t jump_target;
    uint64_t operand1;
} _PyUOpInstruction;

A uop is a decoded, simplified version of a bytecode instruction. operand1 may hold a pointer (e.g., a cached type object) for specialized uops.

_PyExecutorObject​

// CPython: Include/internal/pycore_optimizer.h:55 _PyExecutorObject
typedef struct _PyExecutorObject {
    PyObject_HEAD
    _PyVMData vm_data;            /* exit counters, code pointer */
    uint32_t n_instructions;
    _PyUOpInstruction instructions[];  /* the compiled trace */
} _PyExecutorObject;

The executor is stored in the inline cache of the ENTER_EXECUTOR opcode. When execution reaches ENTER_EXECUTOR, the uop loop runs until a guard fails or the trace exits.

_PyOptimizerObject​

// CPython: Include/internal/pycore_optimizer.h:110 _PyOptimizerObject
typedef struct {
    PyObject_HEAD
    uint16_t resume_threshold;   /* how many times to execute before optimizing */
    uint16_t backedge_threshold;
    int (*optimize)(struct _PyOptimizer *, PyCodeObject *, _Py_CODEUNIT *,
                    _PyExecutorObject **, int);
} _PyOptimizerObject;

resume_threshold defaults to 16: after 16 executions of the RESUME at function entry, the optimizer tries to build a trace.

_PyOptimizer_Optimize​

// CPython: Include/internal/pycore_optimizer.h:165 _PyOptimizer_Optimize
int
_PyOptimizer_Optimize(PyThreadState *tstate, _Py_CODEUNIT *start,
                      PyObject *locals, _PyExecutorObject **exec_ptr);
/* Returns 0 on success (exec_ptr filled), -1 on failure (no executor) */
/* Called when an instruction's counter saturates */

gopy notes​

The tier-2 optimizer is in gopy at compile/flowgraph_passes.go (optimization passes on the flowgraph IR). The _PyExecutorObject / uop loop model maps to gopy's vm/eval_gen.go dispatch table. _PyOptimizerObject resume thresholds are emulated via a counter in vm.Frame that triggers re-specialization.