// Python/ceval.c

/* 基于 PyCodeObject、全局名字空間、局部名字空間，創(chuàng)建棧幀
 * 參數(shù)非常簡單，所以它一般適用于模塊這種參數(shù)不復雜的場景
 * 我們說模塊也會對應一個棧幀，并且它位于棧幀鏈的最頂層 
 */
PyObject *
PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals);

/* 相比 PyEval_EvalCode 多了很多的參數(shù)
 * 比如里面有位置參數(shù)以及個數(shù)，關鍵字參數(shù)以及個數(shù)
 * 還有默認參數(shù)以及個數(shù)，閉包等等，顯然它用于函數(shù)等復雜場景 
 * 注：此 API 已廢棄，內部不再使用
 */
PyObject *
PyEval_EvalCodeEx(PyObject *_co, PyObject *globals, PyObject *locals,
                  PyObject *const *args, int argcount,
                  PyObject *const *kws, int kwcount,
                  PyObject *const *defs, int defcount,
                  PyObject *kwdefs, PyObject *closure);

// Python/ceval.c
PyObject *
PyEval_EvalFrame(PyFrameObject *f)
{
    PyThreadState *tstate = _PyThreadState_GET();
    return _PyEval_EvalFrame(tstate, f->f_frame, 0);
}

PyObject *
PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
{
    PyThreadState *tstate = _PyThreadState_GET();
    return _PyEval_EvalFrame(tstate, f->f_frame, throwflag);
}

// Include/internal/pycore_ceval.h
static inline PyObject*
_PyEval_EvalFrame(PyThreadState *tstate, 
                  struct _PyInterpreterFrame *frame, 
                  int throwflag)
{   
    EVAL_CALL_STAT_INC(EVAL_CALL_TOTAL);
    // 如果 tstate->interp->eval_frame 為 NULL
    // 會調用 _PyEval_EvalFrameDefault 函數(shù)執(zhí)行字節(jié)碼
    if (tstate->interp->eval_frame == NULL) {
        return _PyEval_EvalFrameDefault(tstate, frame, throwflag);
    }
    // 另外虛擬機也支持自定義，允許我們替換掉 _PyEval_EvalFrameDefault
    // 只需將具體實現(xiàn)賦值給 tstate->interp->eval_frame 即可
    // 因此這個做法就使得性能分析器、調試器等工具的實現(xiàn)成為可能
    return tstate->interp->eval_frame(tstate, frame, throwflag);
}

// Python/ceval.c
PyObject *
_PyEval_Vector(PyThreadState *tstate, PyFunctionObject *func,
               PyObject *locals,
               PyObject* const* args, size_t argcount,
               PyObject *kwnames)
{
    // 解釋一下相關參數(shù)的含義
    /* tstate：線程狀態(tài)對象（在后續(xù)的章節(jié)剖析）
     * func：函數(shù)對象（在后續(xù)的章節(jié)剖析）
     * locals：局部名字空間
     * args：調用函數(shù)時傳遞的參數(shù)
     * argcount：通過位置參數(shù)傳遞的參數(shù)的個數(shù)
     * kwnames：通過關鍵字參數(shù)傳遞的參數(shù)的名稱

     舉個例子，比如調用是 func(1, 2, 3, c=4, d=5)
     那么 args 就是 (1, 2, 3, 4, 5)
     argcount 就是 3，因為有 3 個參數(shù)通過位置參數(shù)的方式傳遞
     kwname 則是 ("c", "d")
    */

    // 增加引用計數(shù)
    Py_INCREF(func);  
    Py_XINCREF(locals);
    // 給通過位置參數(shù)傳遞的參數(shù)，增加引用計數(shù)
    for (size_t i = 0; i < argcount; i++) {
        Py_INCREF(args[i]);
    }
    // 給通過關鍵字參數(shù)傳遞的參數(shù)，增加引用計數(shù)
    if (kwnames) {
        Py_ssize_t kwcount = PyTuple_GET_SIZE(kwnames);
        for (Py_ssize_t i = 0; i < kwcount; i++) {
            Py_INCREF(args[i+argcount]);
        }
    }
    // 為即將執(zhí)行的函數(shù)調用，創(chuàng)建一個新的 _PyInterpreterFrame 結構體實例
    // 然后推入虛擬機為其準備的 Stack 中
    _PyInterpreterFrame *frame = _PyEvalFramePushAndInit(
        tstate, func, locals, args, argcount, kwnames);
    if (frame == NULL) {
        return NULL;
    }
    // 計數(shù)器，統(tǒng)計 _PyEval_Vector 的調用次數(shù)，用于跟蹤，我們不用關心
    EVAL_CALL_STAT_INC(EVAL_CALL_VECTOR);
    // 調用 _PyEval_EvalFrame 函數(shù)
    return _PyEval_EvalFrame(tstate, frame, 0);
}

code_string = """
a = 1
b = 2
c = a + b
"""
code_object = compile(code_string, "<file>", "exec")
# 查看常量池
print(code_object.co_consts)
"""
(1, 2, None)
"""
# 查看符號表
print(code_object.co_names)
"""
('a', 'b', 'c')
"""

/* 常量池：(1, 2, None)
 * 符號表：('a', 'b', 'c')
 */
 
// 第一列表示源代碼行號
// 第二列表示指令的偏移量
// 第三列表示指令，在 C 中它們都是宏，表示整數(shù)
// 第四列表示指令參數(shù)
// 第五列是 dis 模塊為了方便我們閱讀而補充的提示信息

0           0 RESUME                   0

// 指令：LOAD_CONST，指令參數(shù)：0
// 表示從常量池中加載索引為 0 的常量，并壓入運行時棧（關于運行時棧，一會兒詳細說明）
// 索引為 0 的常量顯然是 1，而括號里面的提示信息顯示的也是 1
2           2 LOAD_CONST               0 (1)
// 指令：STORE_NAME，指令參數(shù)：0
// 表示從符號表中加載索引為 0 的符號，顯然結果是 "a"
// 然后彈出運行時棧的棧頂元素，顯然是上一條指令壓入的 1
// 將 "a" 和 1 組成鍵值對，存儲在當前的名字空間中
// 到此 a = 1 這條語句便完成了，或者說完成了變量和值的綁定
            4 STORE_NAME               0 (a)

// 從常量池中加載索引為 1 的常量（結果是 2），并壓入運行時棧
3           6 LOAD_CONST               1 (2)
// 從符號表中加載索引為 1 的符號（結果是 "b")
// 然后從棧頂彈出元素 2，將 "b" 和 2 綁定起來
            8 STORE_NAME               1 (b)

// 加載符號表中索引為 0 的符號對應的值，并壓入運行時棧
4          10 LOAD_NAME                0 (a)
// 加載符號表中索引為 1 的符號對應的值，并壓入運行時棧
           12 LOAD_NAME                1 (b)
// 將運行時棧的兩個元素彈出，并執(zhí)行加法運算
// 將運算之后的結果（a + b）再壓入運行時棧           
           14 BINARY_OP                0 (+)
// 從符號表中加載索引為 2 的符號，結果是 "c"           
// 將運行時棧的棧頂元素彈出，這里是 a + b 的運算結果
// 然后進行綁定，完成 c = a + b 這條賦值語句              
           18 STORE_NAME               2 (c)
// 從常量池中加載索引為 2 的元素并返回，有一個隱式的 return None
           20 RETURN_CONST             2 (None)

"""
 0 RESUME                   0
 2 LOAD_CONST               0
 4 STORE_NAME               0
 6 LOAD_CONST               1
 8 STORE_NAME               1
10 LOAD_NAME                0
12 LOAD_NAME                1
14 BINARY_OP                0 (+)
18 STORE_NAME               2
20 RETURN_CONST             2
"""
CACHE = 0
STORE_NAME = 90
LOAD_CONST = 100
LOAD_NAME = 101
RETURN_CONST = 121
BINARY_OP = 122
RESUME = 151

codes = [
    RESUME, 0,

    # a = 1
    LOAD_CONST, 0,
    STORE_NAME, 0,

    # b = 2
    LOAD_CONST, 1,
    STORE_NAME, 1,

    # c = a + b
    LOAD_NAME, 0,  # 加載 a
    LOAD_NAME, 1,  # 加載 b
    BINARY_OP, 0,  # 計算 a + b
    # 從 dis 的輸出信息可以看到，索引為 16 的指令沒有顯示
    # 這是因為索引為 16 的指令和相應的指令參數(shù)都是 0
    # 也就是說，在將 c 和 a + b 綁定之前，插入了一條 CACHE 指令
    # 這條指令是做什么的，我們后續(xù)再探討
    CACHE, 0,
    STORE_NAME, 2,

    # 所有代碼塊都隱式地包含了一個 return None
    RETURN_CONST, 2
]

print(bytes(codes))
"""
b'\x97\x00d\x00Z\x00d\x01Z\x01e\x00e\x01z\x00\x00\x00Z\x02y\x02'
"""

// Inlcude/internal/pycore_frame.h

// 獲取 localsplus 字段
static inline PyObject**
_PyFrame_GetLocalsArray(_PyInterpreterFrame *frame)
{
    return frame->localsplus;
}

// 獲取指針（PyObject **），它指向運行時棧的棧頂，我們稱之為 stack_pointer
// 而元素的入棧和出棧，顯然都是通過操作 stack_pointer 完成的
// 執(zhí)行 *stack_pointer++ = v，一個元素就入棧了
// 執(zhí)行 v = *--stack_pointer，一個元素就出棧了
static inline PyObject**
_PyFrame_GetStackPointer(_PyInterpreterFrame *frame)
{
    // localsplus + stacktop 便指向運行時棧的棧頂
    // 因為 stacktop 的含義就是棧頂相對于 localsplus 數(shù)組（首元素的地址）的偏移量
    PyObject **sp = frame->localsplus + frame->stacktop;
    frame->stacktop = -1;
    return sp;
}

// 隨著元素的入棧和出棧，運行時棧的棧頂、或者說 stack_pointer 也在不斷變化
// 而 frame->stacktop 表示棧頂相對于 localsplus 的偏移量
// 那么顯然，由于棧頂發(fā)生變化，后續(xù)還要對 frame->stacktop 進行更新
static inline void
_PyFrame_SetStackPointer(_PyInterpreterFrame *frame, PyObject **stack_pointer)
{
    frame->stacktop = (int)(stack_pointer - frame->localsplus);
}

#define STACK_LEVEL()  ((int)(stack_pointer - _PyFrame_Stackbase(frame)))

// Include/internal/pycore_frame.h

// PyCodeObject 對象里面有以下幾個字段
// co_nlocals：代碼塊中局部變量的個數(shù)，也包括參數(shù)
// co_ncellvars：cell 變量的個數(shù)，即 co_cellvars 的長度
// co_nfreevars：free 變量的個數(shù)，即 co_freevars 的長度
// co_nlocalsplus：局部變量、cell 變量、free 變量的個數(shù)之和
static inline PyObject **_PyFrame_Stackbase(_PyInterpreterFrame *f) {
    // 由于 co_nlocalsplus = co_nlocals + co_ncellvars + co_nfreevars
    // 那么顯然，f->localsplus + f->f_code->co_nlocalsplus
    // 便指向運行時棧的棧底，或者說運行時棧對應的內存區(qū)域的首元素
    return f->localsplus + f->f_code->co_nlocalsplus;
}

#define STACK_SIZE()      (frame->f_code->co_stacksize)

import dis

def some_func():
    a = 1
    b = 2
    c = 3

# 這里我們只保留字節(jié)碼指令
dis.dis(some_func)
"""
RESUME
LOAD_CONST    # 將元素壓入運行時棧，棧里的元素個數(shù)為 1
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0
LOAD_CONST    # 將元素壓入運行時棧，棧里的元素個數(shù)為 1
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0 
LOAD_CONST    # 將元素壓入運行時棧，棧里的元素個數(shù)為 1 
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0 
RETURN_CONST
"""
# 也就是說，運行時棧只要能容納一個元素，即可執(zhí)行這段代碼
print(some_func.__code__.co_stacksize)  # 1

import dis

def some_func():
    a = 1
    b = 2
    c = 3
    lst = [a, b, c]

dis.dis(some_func)
"""
RESUME       
LOAD_CONST    # 將元素壓入運行時棧，棧里的元素個數(shù)為 1     
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0  
LOAD_CONST    # 將元素壓入運行時棧，棧里的元素個數(shù)為 1   
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0   
LOAD_CONST    # 將元素壓入運行時棧，棧里的元素個數(shù)為 1   
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0    

LOAD_FAST     # 將元素壓入運行時棧，棧里的元素個數(shù)為 1 
LOAD_FAST     # 將元素壓入運行時棧，棧里的元素個數(shù)為 2   
LOAD_FAST     # 將元素壓入運行時棧，棧里的元素個數(shù)為 3   
BUILD_LIST    # 將棧里的三個元素彈出，構建列表并入棧（此時元素個數(shù)為 1）
STORE_FAST    # 將元素從棧頂彈出，棧里的元素個數(shù)為 0      
RETURN_CONST        
"""
# 不難看出，要想執(zhí)行這段代碼，運行時棧要能容納 3 個元素
print(some_func.__code__.co_stacksize)  # 3

#define EMPTY()           (STACK_LEVEL() == 0)

#define TOP()             (stack_pointer[-1])

#define SECOND()       (stack_pointer[-2])

#define THIRD()        (stack_pointer[-3])

#define FOURTH()      (stack_pointer[-4])

#define PEEK(n)       (stack_pointer[-(n)])

#define SET_TOP(v)    (stack_pointer[-1] = (v))

#define SET_SECOND(v)    (stack_pointer[-2] = (v))

#define POKE(n, v)        (stack_pointer[-(n)] = (v))

#define PUSH(v)           BASIC_PUSH(v)
#define BASIC_PUSH(v)     (*stack_pointer++ = (v))

#define POP()             BASIC_POP()
#define BASIC_POP()       (*--stack_pointer)

#define STACK_GROW(n)          BASIC_STACKADJ(n)
#define BASIC_STACKADJ(n)      (stack_pointer += n)

PUSH(2);
PUSH(3);

STACK_GROW(2);
// 設置元素
POKE(1, 3);  // stack_pointer[-1] = 3
POKE(2, 2);  // stack_pointer[-2] = 2

#define STACK_SHRINK(n)        BASIC_STACKADJ(-(n))
#define BASIC_STACKADJ(n)      (stack_pointer += n)