CPython 바이트코드 인터프리터 Deep Dive — ceval.c, Specializing Adaptive, PEP 659, Copy-and-Patch JIT 완전 정복 (2025)

x + y

typedef struct _longobject {
    PyObject_VAR_HEAD
    digit ob_digit[1];
} PyLongObject;

Py_INCREF(obj);  // 카운트 +1
Py_DECREF(obj);  // 카운트 -1, 0이면 해제

Python source (hello.py)
     ↓
Lexer (tokenizer)
     ↓
Parser
     ↓
AST (abstract syntax tree)
     ↓
Compiler (ast → bytecode)
     ↓
Bytecode (code object)
     ↓
ceval.c interpreter
     ↓
실행

import tokenize
import io

code = "x = 1 + 2\n"
tokens = list(tokenize.tokenize(io.BytesIO(code.encode()).readline))
for t in tokens:
    print(t)

# TokenInfo(type=ENCODING, string='utf-8', ...)
# TokenInfo(type=NAME, string='x', ...)
# TokenInfo(type=OP, string='=', ...)
# TokenInfo(type=NUMBER, string='1', ...)
# TokenInfo(type=OP, string='+', ...)
# ...

import ast
tree = ast.parse("x = 1 + 2")
print(ast.dump(tree, indent=2))

Module(
  body=[
    Assign(
      targets=[Name(id='x', ctx=Store())],
      value=BinOp(
        left=Constant(value=1),
        op=Add(),
        right=Constant(value=2)))],
  type_ignores=[])

def add(a, b):
    return a + b

print(add.__code__)
print(add.__code__.co_code)       # 바이트코드 (bytes)
print(add.__code__.co_consts)     # 상수들
print(add.__code__.co_names)      # 글로벌 이름
print(add.__code__.co_varnames)   # 로컬 이름

magic number (버전)
source mtime or hash
source size
marshaled code object

import dis

def add(a, b):
    return a + b

dis.dis(add)

  2           0 RESUME                   0
  3           2 LOAD_FAST                0 (a)
              4 LOAD_FAST                1 (b)
              6 BINARY_OP                0 (+)
             10 RETURN_VALUE

LOAD_FAST  0  # 스택: [a]
LOAD_FAST  1  # 스택: [a, b]
BINARY_OP  0  # a, b pop → a+b push. 스택: [a+b]
RETURN_VALUE  # 스택 top 반환.

LOAD_FAST  0
LOAD_FAST  1
BINARY_ADD    # BINARY_SUB, BINARY_MULT 등 각자

LOAD_FAST  0
LOAD_FAST  1
BINARY_OP  0  # 0=+, 5=*, 등. 통합된 하나

def fib(n):
    if n < 2:
        return n
    return fib(n-1) + fib(n-2)

  2           0 RESUME                   0
  3           2 LOAD_FAST                0 (n)
              4 LOAD_CONST               1 (2)
              6 COMPARE_OP              40 (<)
             10 POP_JUMP_IF_FALSE       6 (to 24)
  4          12 LOAD_FAST                0 (n)
             14 RETURN_VALUE
  5     >>   24 LOAD_GLOBAL              1 (NULL + fib)
             36 LOAD_FAST                0 (n)
             38 LOAD_CONST               1 (2)
             40 BINARY_OP               10 (-)
             44 CALL                     1
             52 LOAD_GLOBAL              1 (NULL + fib)
             64 LOAD_FAST                0 (n)
             66 LOAD_CONST               2 (1)
             68 BINARY_OP               10 (-)
             72 CALL                     1
             80 BINARY_OP                0 (+)
             84 RETURN_VALUE

typedef struct _PyInterpreterFrame {
    PyFunctionObject *f_funcobj;
    PyObject *f_builtins;
    PyObject *f_globals;
    PyObject *f_locals;
    PyCodeObject *f_code;
    PyObject *frame_obj;
    struct _PyInterpreterFrame *previous;
    _Py_CODEUNIT *prev_instr;  // 현재 명령어
    int stacktop;
    bool is_entry;
    char owner;
    PyObject *localsplus[1];   // 로컬 + 스택 (flex array)
} _PyInterpreterFrame;

PyObject *
_PyEval_EvalFrameDefault(_PyInterpreterFrame *frame, int throwflag)
{
    _Py_CODEUNIT *next_instr = frame->prev_instr + 1;
    PyObject **stack_pointer = _PyFrame_GetStackPointer(frame);

    while (1) {
        _Py_CODEUNIT word = *next_instr++;
        int opcode = _Py_OPCODE(word);
        int oparg = _Py_OPARG(word);

        switch (opcode) {
            case LOAD_FAST: {
                PyObject *value = frame->localsplus[oparg];
                Py_INCREF(value);
                *stack_pointer++ = value;
                DISPATCH();
            }
            case LOAD_CONST: {
                PyObject *value = PyTuple_GET_ITEM(
                    frame->f_code->co_consts, oparg);
                Py_INCREF(value);
                *stack_pointer++ = value;
                DISPATCH();
            }
            case BINARY_OP: {
                PyObject *right = *(--stack_pointer);
                PyObject *left = *(--stack_pointer);
                PyObject *result = binary_op(left, right, oparg);
                Py_DECREF(left);
                Py_DECREF(right);
                if (result == NULL) goto error;
                *stack_pointer++ = result;
                DISPATCH();
            }
            case RETURN_VALUE: {
                PyObject *retval = *(--stack_pointer);
                // frame 정리
                return retval;
            }
            // ... 수백 개 case
        }
    }
}

#define DISPATCH() goto *opcode_targets[opcode];

static void *opcode_targets[] = {
    [LOAD_FAST] = &&LOAD_FAST_LABEL,
    [LOAD_CONST] = &&LOAD_CONST_LABEL,
    ...
};

LOAD_FAST_LABEL:
    // ... handler ...
    DISPATCH();

LOAD_CONST_LABEL:
    // ...
    DISPATCH();

def outer():
    x = 1
    inner()

def inner():
    print("hi")

outer()

Frame stack:
  inner frame  (top)
  outer frame
  <module> frame  (bottom)

import traceback

def inner():
    raise ValueError("oops")

def outer():
    inner()

try:
    outer()
except:
    traceback.print_exc()

Traceback (most recent call last):
  File "a.py", line 8, in <module>
    outer()
  File "a.py", line 6, in outer
    inner()
  File "a.py", line 3, in inner
    raise ValueError("oops")

import sys
frame = sys._getframe()
print(frame.f_code.co_name)   # 현재 함수 이름
print(frame.f_locals)          # 로컬 변수 dict
print(frame.f_back)            # 호출자 frame

def get(obj):
    return obj.name

LOAD_ATTR  0  ← 일반 opcode

첫 실행 시:
  - 프로파일링: obj type, offset 기록
  - Opcode를 LOAD_ATTR_INSTANCE_VALUE로 교체 (내부에서만)
  
다음 실행 시:
  - 새로운 specialized 버전 사용
  - Type 확인 (가정한 type과 같은가?)
  - 같으면: 직접 offset으로 접근 (매우 빠름)
  - 다르면: 원래 LOAD_ATTR로 fallback

[LOAD_ATTR opcode (2 bytes)] [cache slot (여러 바이트)]

BINARY_OP_ADD_INT
BINARY_OP_ADD_FLOAT
BINARY_OP_ADD_UNICODE
BINARY_OP_MULTIPLY_INT
BINARY_OP_SUBTRACT_INT
...

def add(a, b):
    return a + b

add(1, 2)      # → BINARY_OP_ADD_INT
add(1.0, 2.0)  # → INT 가정 실패 → 원래 BINARY_OP로 fallback

PyInterpreterState *sub = Py_NewInterpreter();
// 새 interpreter에서 코드 실행
Py_EndInterpreter(sub);

프로세스
├── Main Interpreter (GIL 1)
├── Sub 1 (GIL 2)  ← 독립 병렬 실행
└── Sub 2 (GIL 3)  ← 독립 병렬 실행

import interpreters

interp = interpreters.create()
interp.run("""
import math
print(math.pi)
""")

./configure --disable-gil
make
./python

// 빌드 시 컴파일된 템플릿:
// (pseudo code)
const char LOAD_FAST_template[] = {
    // mov rax, [rdi + <FRAME_OFFSET_PLACEHOLDER>]
    0x48, 0x8B, 0x47, 0x00, 0x00, 0x00, 0x00,
    // push rax
    0x50,
    ...
};

// 런타임:
memcpy(code_buffer, LOAD_FAST_template, sizeof(LOAD_FAST_template));
patch_offset(code_buffer + 3, actual_offset);

def count_up():
    n = 0
    while True:
        yield n
        n += 1

gen = count_up()
next(gen)  # 0
next(gen)  # 1
next(gen)  # 2

gen = count_up()
  ↓
Frame 생성, n=0
  ↓
next(gen) → 루프 진입 → yield 0 → frame suspend
  ↓
next(gen) → frame resume → n += 1 → yield 1 → suspend
  ↓
...

async def fetch():
    data = await download()
    return process(data)

async def outer():
    return await inner()

import math

a.py

__pycache__/a.cpython-312.pyc

# 전통: timestamp 기반
python -m py_compile a.py

# hash 기반 (3.7+)
python -m py_compile --invalidation-mode=checked_hash a.py

>>> import sys
>>> sys.modules['_frozen_importlib']
<module '_frozen_importlib' (frozen)>

try:
    risky()
except ValueError:
    handle()

SETUP_FINALLY   target
  risky()
POP_BLOCK
  JUMP_FORWARD
target:
  <예외 처리 경로>

exception_table:
  [bytecode range] → [handler location, stack_depth]

import cProfile
cProfile.run("myfunc()")

         43 function calls in 0.005 seconds

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
        1    0.000    0.000    0.005    0.005 <string>:1(<module>)
       10    0.001    0.000    0.005    0.000 a.py:5(work)
       30    0.004    0.000    0.004    0.000 a.py:2(helper)

@profile
def myfunc():
    # 줄 단위 시간 측정

sum(xs)  # 빠름
# vs
total = 0
for x in xs: total += x  # 느림

def f():
    sqrt = math.sqrt  # local로
    for x in data:
        y = sqrt(x)   # LOAD_FAST (빠름)

[x*2 for x in data]  # 빠름 (특수 최적화)

# fib.pyx
def fib(int n):
    cdef int a = 0, b = 1
    for _ in range(n):
        a, b = b, a + b
    return a

import dis
dis.dis(my_function)
dis.show_code(my_function.__code__)

import gc
gc.get_objects()       # 모든 객체
gc.collect()           # 수동 GC
gc.get_threshold()     # generational 임계
gc.set_debug(gc.DEBUG_STATS)

import sys
sys.getsizeof(obj)     # 객체 크기 (바이트)
sys.getrefcount(obj)   # 참조 카운트
sys.settrace(tracer)   # 모든 함수 호출 훅
sys.getframeinfo(frame)

import tracemalloc
tracemalloc.start()
# ... code ...
snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')
for stat in top_stats[:10]:
    print(stat)

Python 3.10: baseline
Python 3.11: 1.25x 빠름
Python 3.12: 1.3x
Python 3.13: ~1.4x (JIT 포함 시)
Python 3.15 예상: 2-3x

┌─────────────────────────────────────────────────────┐
│          CPython Internals Cheat Sheet               │
├─────────────────────────────────────────────────────┤
│ 컴파일 파이프라인:                                      │
│   Source → Lexer → Parser (PEG)                      │
│   → AST → Compiler → Bytecode → Code Object          │
│   → .pyc 캐시                                         │
│                                                       │
│ Bytecode:                                             │
│   Stack-based VM                                      │
│   ~200 opcodes                                        │
│   LOAD_FAST, BINARY_OP, CALL, RETURN_VALUE           │
│   dis 모듈로 확인                                      │
│                                                       │
│ ceval.c:                                              │
│   _PyEval_EvalFrameDefault (메인 루프)                │
│   거대한 switch 또는 computed goto                     │
│   각 opcode = C 코드 handler                          │
│                                                       │
│ Frame:                                                │
│   _PyInterpreterFrame                                 │
│   로컬 + 스택 (localsplus 배열)                        │
│   Python 3.11+: C stack 할당 (빠름)                  │
│                                                       │
│ PEP 659 (3.11+):                                      │
│   Specializing adaptive interpreter                   │
│   Inline cache (바이트코드 옆)                         │
│   Opcode를 specialized version으로 in-place 교체      │
│   LOAD_ATTR_INSTANCE_VALUE                            │
│   BINARY_OP_ADD_INT                                   │
│   De-optimize on fail                                 │
│   +25% 성능                                           │
│                                                       │
│ PEP 684 (3.12):                                       │
│   Per-interpreter GIL                                 │
│   서브인터프리터 진짜 병렬                              │
│                                                       │
│ PEP 703 (3.13):                                       │
│   Free-threaded build                                 │
│   GIL 제거 (실험)                                      │
│   Biased reference counting                          │
│                                                       │
│ PEP 744 (3.13):                                       │
│   Copy-and-patch JIT                                  │
│   템플릿 기반 초고속 컴파일                             │
│   Tier 2 optimizer                                    │
│   실험적                                               │
│                                                       │
│ Generator / async:                                    │
│   Frame suspension                                    │
│   yield / await = frame 보존                          │
│                                                       │
│ Exception (3.11+):                                    │
│   Zero-cost exception handling                        │
│   Exception table                                    │
│                                                       │
│ 성능 툴:                                                │
│   cProfile, line_profiler, py-spy                    │
│   tracemalloc, gc module                              │
│                                                       │
│ 대안 구현:                                              │
│   PyPy (JIT)                                         │
│   Cython (C 컴파일)                                   │
│   MicroPython, RustPython                             │
│   Mojo, Codon (2024+)                                 │
└─────────────────────────────────────────────────────┘