// Python/ceval.c
PyObject* _Py_HOT_FUNCTION
_PyEval_EvalFrameDefault(PyThreadState *tstate, 
                         _PyInterpreterFrame *frame, 
                         int throwflag)
{   
    // 檢測(cè)線(xiàn)程狀態(tài)對(duì)象是否不為 NULL
    // 如果為 NULL，說(shuō)明 GIL 被釋放，而這是不允許的
    // 字節(jié)碼指令必須在當(dāng)前線(xiàn)程持有 GIL 的情況下執(zhí)行
    _Py_EnsureTstateNotNULL(tstate);
    // _PyEval_EvalFrameDefault 的調(diào)用次數(shù)加 1
    CALL_STAT_INC(pyeval_calls);

// 如果使用 "計(jì)算跳轉(zhuǎn)"，導(dǎo)入靜態(tài)跳轉(zhuǎn)表
#if USE_COMPUTED_GOTOS
#include "opcode_targets.h"
#endif

    // ...
}

for (;;) {
    // 循環(huán)遍歷指令集，獲取指令和指令參數(shù)
    uint8_t opcode = ...;  // 指令
    int oparg = ...;  // 指令參數(shù)
    // 執(zhí)行對(duì)應(yīng)的處理邏輯
    switch (opcode) {
        case LOAD_CONST:
            處理邏輯;
        case LOAD_FAST:
            處理邏輯;
        case LOAD_FAST:
            處理邏輯;
        case BUILD_LIST: 
            處理邏輯;
        case DICT_UPDATE: 
            處理邏輯;
        // ...
    }
}

#include <stdio.h>

void label_as_value(int jump) {
    int num = 4;
    void *label;
    switch (num) {
        case 1:
            printf("%d\n", 1);
            break;
        // 在 case 2 分支里面定義了一個(gè)標(biāo)簽叫 two
        case 2: two: {
            printf("%d\n", 2);
            break;
        }
        // 在 case 3 分支里面定義了一個(gè)標(biāo)簽叫 three
        case 3: three: {
            printf("%d\n", 3);
            break;
        }
        case 4:
            printf("%d\n", 4);
            // 如果參數(shù) jump 等于 2，保存 two 標(biāo)簽的地址
            // 如果參數(shù) jump 等于 3，保存 three 標(biāo)簽的地址
            if (jump == 2) label = &&two;
            else if (jump == 3) label = &&three;
            // 跳轉(zhuǎn)到指定標(biāo)簽
            goto *label;
        default:
            break;
    }
}

int main() {
    label_as_value(2);
    // 4
    // 2
    label_as_value(3);
    // 4
    // 3
}

// Python/ceval_macros.h
#define INSTRUCTION_START(op) (frame->prev_instr = next_instr++)

#if USE_COMPUTED_GOTOS
#  define TARGET(op) TARGET_##op: INSTRUCTION_START(op);
#  define DISPATCH_GOTO() goto *opcode_targets[opcode]
#else
#  define TARGET(op) case op: TARGET_##op: INSTRUCTION_START(op);
#  define DISPATCH_GOTO() goto dispatch_opcode
#endif

// Python/ceval_macros.h

// 會(huì)依次調(diào)用 3 個(gè)宏，中間第二個(gè)宏可以忽略掉
#define DISPATCH() \
    { \
        NEXTOPARG(); \
        PRE_DISPATCH_GOTO(); \
        DISPATCH_GOTO(); \
    }

/*
typedef union {
    uint16_t cache;
    struct {
        uint8_t code;
        uint8_t arg;
    } op;
} _Py_CODEUNIT;
*/
// next_instr 指向下一條待執(zhí)行的指令，prev_instr 指向最近一條執(zhí)行完畢的指令
// 所以 prev_instr 的下一條指令就是 next_instr
// 由于在處理指令時(shí)，先執(zhí)行了 frame->prev_instr = next_instr++;
// 所以調(diào)用 NEXTOPARG() 時(shí)，next_instr 已經(jīng)指向了新的待執(zhí)行的字節(jié)碼指令
// 這里獲取指令和指令參數(shù)
#define NEXTOPARG()  do { \
        _Py_CODEUNIT word = *next_instr; \
        opcode = word.op.code; \
        oparg = word.op.arg; \
    } while (0)

// 跳轉(zhuǎn)
#if USE_COMPUTED_GOTOS
#  define DISPATCH_GOTO() goto *opcode_targets[opcode]
#else
#  define DISPATCH_GOTO() goto dispatch_opcode
#endif

PyObject* _Py_HOT_FUNCTION
_PyEval_EvalFrameDefault(PyThreadState *tstate, 
                         _PyInterpreterFrame *frame, 
                         int throwflag)
{
    _Py_EnsureTstateNotNULL(tstate);
    CALL_STAT_INC(pyeval_calls);

#if USE_COMPUTED_GOTOS
#include "opcode_targets.h"
#endif

    uint8_t opcode;  // 指令
    int oparg;       // 指令參數(shù)
    
    /*
    typedef struct _PyCFrame {
        struct _PyInterpreterFrame *current_frame;
        struct _PyCFrame *previous;
    } _PyCFrame;

    結(jié)構(gòu)體位于 Include/cpython/pystate.h 中
    */
    // _PyCFrame 相當(dāng)于對(duì) _PyInterpreterFrame 做了一層封裝
    // 為了方便描述，我們也稱(chēng) _PyCFrame 實(shí)例為棧楨
    // cframe 會(huì)在 C 語(yǔ)言的調(diào)用棧中傳遞，從而提高性能
    _PyCFrame cframe;
    // 入口幀
    _PyInterpreterFrame  entry_frame;
    PyObject *kwnames = NULL;

    // tstate 表示線(xiàn)程狀態(tài)對(duì)象，tstate->cframe 指向正在執(zhí)行的棧楨
    // 那么顯然要將 tstate->cframe 更新為 &cframe
    // 不過(guò)更新之前，要先將目前的 tstate->cframe 保存起來(lái)
    // 因?yàn)檫M(jìn)入到幀評(píng)估函數(shù)中，說(shuō)明開(kāi)啟了新的幀，也意味著它成為了上一個(gè)幀
    _PyCFrame *prev_cframe = tstate->cframe;
    cframe.previous = prev_cframe;  // 通過(guò) previous 保存上一個(gè)幀
    tstate->cframe = &cframe;       // 指向當(dāng)前幀

    // 對(duì)入口幀內(nèi)部的屬性初始化
    entry_frame.f_code = tstate->interp->interpreter_trampoline;
    entry_frame.prev_instr =
        _PyCode_CODE(tstate->interp->interpreter_trampoline);
    entry_frame.stacktop = 0;
    entry_frame.owner = FRAME_OWNED_BY_CSTACK;
    entry_frame.return_offset = 0;
    /* Push frame */
    entry_frame.previous = prev_cframe->current_frame;
    // frame 是 _PyEval_Vector 內(nèi)部創(chuàng)建的棧楨，也就是當(dāng)前正在執(zhí)行的幀
    // _PyEval_Vector 創(chuàng)建完棧楨后，會(huì)將它作為參數(shù)，調(diào)用幀評(píng)估函數(shù)
    // 而 frame->previous 同樣指向上一個(gè) _PyInterpreterFrame
    // 這里將它賦值為 &entry_frame，即入口幀
    frame->previous = &entry_frame;
    // cframe 和 frame 都可以理解為正在執(zhí)行的棧楨
    // 但前者對(duì)后者做了一層封裝，這里將 cframe.current_frame 賦值為 frame 
    cframe.current_frame = frame;

    // 判斷還能否安全地進(jìn)行遞歸調(diào)用
    // 如果不能，就減少遞歸計(jì)數(shù)并跳轉(zhuǎn)到退出邏輯
    tstate->c_recursion_remaining -= (PY_EVAL_C_STACK_UNITS - 1);
    if (_Py_EnterRecursiveCallTstate(tstate, "")) {
        tstate->c_recursion_remaining--;
        tstate->py_recursion_remaining--;
        goto exit_unwind;
    }

    // next_instr 剛才說(shuō)過(guò)的，它指向下一條待執(zhí)行的指令
    // 通過(guò)不斷執(zhí)行 frame->prev_instr = next_instr++
    // 最終完成整個(gè)字節(jié)碼指令集的遍歷
    _Py_CODEUNIT *next_instr;
    // stack_pointer 指向運(yùn)行時(shí)棧的棧頂
    // 元素的入棧和出棧，都是通過(guò)操作 stack_pointer 實(shí)現(xiàn)的
    PyObject **stack_pointer;

// 一個(gè)宏，負(fù)責(zé)初始化 next_instr 和 stack_pointer
// 但里面有一個(gè) _PyInterpreterFrame_LASTI 函數(shù)需要說(shuō)一下
// 我們說(shuō) prev_instr 指向上一條、或者最近一條執(zhí)行完畢的字節(jié)碼指令
// 那么 prev_instr 的偏移量是多少呢？這個(gè)還是很簡(jiǎn)單的
// 用 frame->prev_instr - _PyCode_CODE(f_code) 即可
// 而這個(gè)偏移量在以前的版本中，會(huì)有一個(gè)專(zhuān)門(mén)的棧楨字段（f_lasti）保存
#define SET_LOCALS_FROM_FRAME() \
    assert(_PyInterpreterFrame_LASTI(frame) >= -1); \
    next_instr = frame->prev_instr + 1; \
    stack_pointer = _PyFrame_GetStackPointer(frame);

// 開(kāi)始在棧楨中執(zhí)行字節(jié)碼了，但還要做一下檢測(cè)
// 判斷函數(shù)的調(diào)用層級(jí)是否超過(guò)了最大深度（默認(rèn) 1000）
start_frame:
    if (_Py_EnterRecursivePy(tstate)) {
        goto exit_unwind;
    }

// 調(diào)用宏 SET_LOCALS_FROM_FRAME，初始化 next_instr 和 stack_pointer
resume_frame:
    SET_LOCALS_FROM_FRAME();

// ...
}

PyObject* _Py_HOT_FUNCTION
_PyEval_EvalFrameDefault(PyThreadState *tstate, 
                         _PyInterpreterFrame *frame, 
                         int throwflag)
{
    // ...  
    // ...

    // 開(kāi)始進(jìn)行調(diào)度，準(zhǔn)備執(zhí)行字節(jié)碼  
    DISPATCH();
handle_eval_breaker:
    if (_Py_HandlePending(tstate) != 0) {
        goto error;
    }
    DISPATCH();

    {
    /* Start instructions */
    // 如果不使用計(jì)算跳轉(zhuǎn)，那么這里就是帶標(biāo)簽的 switch 語(yǔ)句
    // 如果使用計(jì)算跳轉(zhuǎn)，那么這兩行無(wú)效
#if !USE_COMPUTED_GOTOS
    dispatch_opcode:
        switch (opcode)
#endif
        {

// 導(dǎo)入 generated_cases.c.h，還記得這個(gè)文件嗎？里面包含了指令的處理邏輯
// 如果不使用計(jì)算跳轉(zhuǎn)，那么宏 TARGET 展開(kāi)之后會(huì)生成一個(gè)帶標(biāo)簽的 case 語(yǔ)句 
// 如果使用計(jì)算跳轉(zhuǎn)，那么宏 TARGET 展開(kāi)之后就只有一個(gè)標(biāo)簽
#include "generated_cases.c.h"
        
        // ...

        } /* End instructions */
        Py_UNREACHABLE();
    }
    // ...
}

PyObject* _Py_HOT_FUNCTION
_PyEval_EvalFrameDefault(PyThreadState *tstate, 
                         _PyInterpreterFrame *frame, 
                         int throwflag)
{
    // ...
    {
        // ...

// 如果執(zhí)行時(shí)出現(xiàn) UnboundLocalError，會(huì)跳轉(zhuǎn)到此標(biāo)簽
unbound_local_error:
        {
            format_exc_check_arg(tstate, PyExc_UnboundLocalError,
                UNBOUNDLOCAL_ERROR_MSG,
                PyTuple_GetItem(frame->f_code->co_localsplusnames, oparg)
            );
            goto error;
        }

// 如果字節(jié)碼執(zhí)行時(shí)報(bào)錯(cuò)了，但運(yùn)行時(shí)棧里面還有元素
// 那么要將運(yùn)行時(shí)棧里的元素彈出
// 當(dāng)運(yùn)行時(shí)棧里包含 4 個(gè)元素時(shí)，跳轉(zhuǎn)到此標(biāo)簽
pop_4_error:
    STACK_SHRINK(1);
// 當(dāng)運(yùn)行時(shí)棧里包含 3 個(gè)元素時(shí)，跳轉(zhuǎn)到此標(biāo)簽
pop_3_error:
    STACK_SHRINK(1);
// 當(dāng)運(yùn)行時(shí)棧里包含 2 個(gè)元素時(shí)，跳轉(zhuǎn)到此標(biāo)簽
pop_2_error:
    STACK_SHRINK(1);
// 當(dāng)運(yùn)行時(shí)棧里包含 1 個(gè)元素時(shí)，跳轉(zhuǎn)到此標(biāo)簽
pop_1_error:
    STACK_SHRINK(1);
error:
        kwnames = NULL;

        assert(_PyErr_Occurred(tstate));
        assert(frame != &entry_frame);
        // 報(bào)錯(cuò)時(shí)，要生成 traceback
        // 關(guān)于 traceback，等介紹異常捕獲的時(shí)候再說(shuō)
        if (!_PyFrame_IsIncomplete(frame)) {
            PyFrameObject *f = _PyFrame_GetFrameObject(frame);
            if (f != NULL) {
                PyTraceBack_Here(f);
            }
        }
        monitor_raise(tstate, frame, next_instr-1);
exception_unwind:
        // ...
        // 后續(xù)介紹
    }

// ...
}

code_string = """
chinese = 89
math = 99
english = 91
avg = (chinese + math + english) / 3
"""

# 將上面的代碼以模塊的方式進(jìn)行編譯
code_obj = compile(code_string, "...", "exec")
# 查看常量池
print(code_obj.co_consts)  # (89, 99, 91, 3, None)
# 查看符號(hào)表
print(
    code_obj.co_names
)  # ('chinese', 'math', 'english', 'avg')

0           0 RESUME                   0

  2           2 LOAD_CONST               0 (89)
              4 STORE_NAME               0 (chinese)

  3           6 LOAD_CONST               1 (99)
              8 STORE_NAME               1 (math)

  4          10 LOAD_CONST               2 (91)
             12 STORE_NAME               2 (english)

  5          14 LOAD_NAME                0 (chinese)
             16 LOAD_NAME                1 (math)
             18 BINARY_OP                0 (+)
             22 LOAD_NAME                2 (english)
             24 BINARY_OP                0 (+)
             28 LOAD_CONST               3 (3)
             30 BINARY_OP               11 (/)
             34 STORE_NAME               3 (avg)
             36 RETURN_CONST             4 (None)

chinese = 89
math = 99
english = 91
avg = (chinese + math + english) / 3

// Python/generated_cases.c.h
TARGET(LOAD_CONST) {
    PREDICTED(LOAD_CONST);
    PyObject *value;
    #line 204 "Python/bytecodes.c"
    // 從常量池中加載索引為 oparg 的常量
    value = GETITEM(frame->f_code->co_consts, oparg);
    // 增加引用計(jì)數(shù)
    Py_INCREF(value);
    #line 114 "Python/generated_cases.c.h"
    // stack_pointer++，為入棧的元素留出一個(gè)空間
    // 我們上一篇專(zhuān)門(mén)介紹了這些運(yùn)行時(shí)棧的 API
    STACK_GROW(1);
    // 將棧頂元素設(shè)置為 value
    stack_pointer[-1] = value;
    // STACK_GROW(1) 和 stack_pointer[-1] = value 組合起來(lái)等價(jià)于 PUSH(value)
    // 調(diào)用 DISPATCHER，讀取下一條指令，并跳轉(zhuǎn)到指定位置進(jìn)行處理
    DISPATCH();
}


// Python/ceval_macros.h
static inline PyObject *
GETITEM(PyObject *v, Py_ssize_t i) {
    // 從元組 v 中獲取索引為 i 的元素
    assert(PyTuple_Check(v));
    assert(i >= 0);
    assert(i < PyTuple_GET_SIZE(v));
    return PyTuple_GET_ITEM(v, i);
}

TARGET(STORE_NAME) {
    // 獲取運(yùn)行時(shí)棧的棧頂元素，顯然是上一步壓入的 89
    PyObject *v = stack_pointer[-1];
    #line 1013 "Python/bytecodes.c"
    // 從符號(hào)表中加載索引為 oparg 的符號(hào)  
    // 符號(hào)本質(zhì)上就是一個(gè) PyUnicodeObject 對(duì)象
    // 這里就是字符串 "chinese"
    PyObject *name = GETITEM(frame->f_code->co_names, oparg);
    // #define LOCALS() frame->f_locals
    // 獲取名字空間（namespace）
    PyObject *ns = LOCALS();
    int err;
    if (ns == NULL) {
        // 如果沒(méi)有名字空間則報(bào)錯(cuò)，設(shè)置異常
        _PyErr_Format(tstate, PyExc_SystemError,
                      "no locals found when storing %R", name);
    #line 1405 "Python/generated_cases.c.h"
        Py_DECREF(v);
    #line 1020 "Python/bytecodes.c"
        if (true) goto pop_1_error;
    }
    // 將符號(hào)和對(duì)象綁定起來(lái)放在名字空間 ns 中
    // 名字空間是一個(gè)字典，PyDict_CheckExact 負(fù)責(zé)檢測(cè) ns 是否為字典
    if (PyDict_CheckExact(ns))
        err = PyDict_SetItem(ns, name, v);
    else
        err = PyObject_SetItem(ns, name, v);
    #line 1414 "Python/generated_cases.c.h"
    // 對(duì)象的引用計(jì)數(shù)減 1
    Py_DECREF(v);
    #line 1027 "Python/bytecodes.c"
    if (err) goto pop_1_error;
    #line 1418 "Python/generated_cases.c.h"
    // 棧收縮，v = stack_pointer[-1] 和 STACK_SHRINK(1)
    // 兩者組合起來(lái)就等價(jià)于 v = POP()，即彈出運(yùn)行時(shí)棧的棧頂元素
    STACK_SHRINK(1);
    DISPATCH();
}

TARGET(LOAD_NAME) {
    PyObject *v;
    #line 1236 "Python/bytecodes.c"
    // 獲取全局名字空間，對(duì)于模塊來(lái)說(shuō)
    // f->f_locals 和 f->f_globals 指向同一個(gè)字典
    PyObject *mod_or_class_dict = LOCALS();
    if (mod_or_class_dict == NULL) {
        _PyErr_SetString(tstate, PyExc_SystemError,
                         "no locals found");
        if (true) goto error;
    }
    // 從符號(hào)表 co_names 中加載索引為 oparg 的符號(hào)
    // 但是注意：全局變量是通過(guò)字典存儲(chǔ)的
    // 所以這里的 name 只是一個(gè)字符串罷了，比如 "chinese"
    // 然后還要再根據(jù)這個(gè)字符串從字典里面查找對(duì)應(yīng)的 value
    PyObject *name = GETITEM(frame->f_code->co_names, oparg);
    // 根據(jù) name 從字典中獲取 value
    if (PyDict_CheckExact(mod_or_class_dict)) {
        v = PyDict_GetItemWithError(mod_or_class_dict, name);
        if (v != NULL) {
            Py_INCREF(v);
        }
        else if (_PyErr_Occurred(tstate)) {
            goto error;
        }
    }
    
    // ...

    #line 1763 "Python/generated_cases.c.h"
    // 將變量的值壓入運(yùn)行時(shí)棧
    STACK_GROW(1);
    stack_pointer[-1] = v;
    DISPATCH();
}

TARGET(BINARY_OP) {
    PREDICTED(BINARY_OP);
    // 獲取棧里的兩個(gè)元素
    PyObject *rhs = stack_pointer[-1];
    PyObject *lhs = stack_pointer[-2];
    // 計(jì)算結(jié)果
    PyObject *res;
    // ...
    // binary_ops[oparg] 會(huì)拿到對(duì)應(yīng)的函數(shù)指針（這里是加法）
    // 然后傳入 lhs 和 rhs 進(jìn)行計(jì)算
    res = binary_ops[oparg](lhs, rhs);
    #line 4663 "Python/generated_cases.c.h"
    // 減少引用計(jì)數(shù)
    Py_DECREF(lhs);
    Py_DECREF(rhs);
    #line 3384 "Python/bytecodes.c"
    if (res == NULL) goto pop_2_error;
    #line 4668 "Python/generated_cases.c.h"
    // 棧里面有兩個(gè)元素，應(yīng)該將它們彈出，然后再將 res 入棧
    // 但事實(shí)上只需彈出一個(gè)，然后再用 res 將棧頂元素替換掉即可
    STACK_SHRINK(1);
    stack_pointer[-1] = res;
    next_instr += 1;
    DISPATCH();
}

# LOAD_CONST 將 89 壓入棧中
# STORE_NAME 將 89 從棧中彈出
# 并將符號(hào) "chinese" 和 89 綁定起來(lái)，放在名字空間中
chinese = 89
print(
    {k: v for k, v in locals().items() if not k.startswith("__")}
)  # {'chinese': 89}

math = 99
print(
    {k: v for k, v in locals().items() if not k.startswith("__")}
)  # {'chinese': 89, 'math': 99}

english = 91
print(
    {k: v for k, v in locals().items() if not k.startswith("__")}
)  # {'chinese': 89, 'math': 99, 'english': 91}

avg = (chinese + math + english) / 3
print(
    {k: v for k, v in locals().items() if not k.startswith("__")}
)  # {'chinese': 89, 'math': 99, 'english': 91, 'avg': 93.0}