# 9.4 值栈

## The Value Stack

在核心的求值循环中会创建一个值栈。这个栈包含了一系列指向 `PyObject` 实例的指针，这些实例可以是变量、函数的引用（在 Python 中也是对象）或其他类型的 Python 对象。

求值循环中的字节码指令将从值栈中获取输入。

## 字节码操作的例子：BINARY\_OR

在前几章我们已经探究了如何将二元操作编译成一条指令。如果你在 Python 使用了 `or` ：

```python
if left or right:
    pass
```

编译器会把操作符 `or` 编译成 `BINARY_OR` 指令：

```c
static int
binop(struct compiler *c, operator_ty op)
{
    switch (op) {
        case Add:
            return BINARY_ADD;
        ...
        case BitOr:
            return BINARY_OR;
        ...
```

在求值循环中，`BINARY_OR` 将从值栈中获取两个值作为左右操作数（`left` 和 `right`），随后以这两个对象作为参数调用函数 `PyNumber_Or()` ：

```c
    ...
    case TARGET(BINARY_OR): {
          PyObject *right = POP();
          PyObject *left = TOP();
          PyObject *res = PyNumber_Or(left, right);
          Py_DECREF(left);
          Py_DECREF(right);
          SET_TOP(res);
          if (res == NULL)
                goto error;
          DISPATCH();
    }
```

最后，将求得的结果 `res` 放在栈的顶部，覆写了当前栈顶的值。

## 模拟值栈

要理解求值循环，那你必须先理解值栈的工作原理。

一种理解是值栈就就像一个木钉，你可以在上面不断的摆放圆柱体。在这种情况下，你一次只能添加或删除一个圆柱体，并且总是添加到堆栈顶部或从堆栈顶部移除。在 CPython 中，你可以使用 `PUSH(a)` 宏将对象添加到值栈中，这里的 `a` 是一个指向 `PyObject` 对象的指针。

假设你创建了一个 `PyLong` 类型且值为 10 的对象，同时你想把它放入值栈中，可以参考下面的例子：

```c
    PyObject *a = PyLong_FromLong(10);
    PUSH(a);
```

这个操作将产生以下效果：

![图9.4.1 值栈的 push 操作](/files/J12DRbE96NF0m69VUrNR)

为了获取这个值，你可以在下一次操作中使用 `POP()` 宏来拿到栈顶的对象。

```c
    PyObject *a = POP(); // a is PyLongObject with a value of 10
```

这个操作将返回栈顶的值，并且操作完成后值栈中不存在任何值：

![图9.4.2 值栈的 pop 操作](/files/PsfHWF6vvUqz3g9QqNYE)

现在假设你添加了两个值到值栈中：

```c
    PyObject *a = PyLong_FromLong(10);
    PyObject *b = PyLong_FromLong(20);
    PUSH(a);
    PUSH(b);
```

值栈内值的顺序与添加的顺序有关，所以 `a` 被添加到了值栈的第二个位置：

![图9.4.3 向值栈添加两个元素](/files/eJ2z5IOJh48xdyVaY1XK)

如果你要去获取一个栈顶的值，你将得到指向 `b` 的指针：

```c
    PyObject *val = POP(); // returns ptr to b
```

![图9.4.4 从值栈取出元素](/files/tqrAzOzyVjEjIlWmt45Z)

如果你想要在不弹出对象的情况下获取指向堆栈中顶部值的指针，那你可以使用 `PEEK(v)` 操作，其中 `v` 是栈中元素的位置：

```c
    PyObject *first = PEEK(0);
```

0 代表栈顶的位置，1 则代表栈中第二个位置：

![图9.4.5 值栈的 peek 操作](/files/7ukltKwcFl48hGnJh3tF)

`DUP_TOP()` 这个宏可以用于克隆栈顶部的值：

```c
    DUP_TOP();
```

这个操作将复制栈顶部的值，形成指向同一对象的两个指针：

![图9.4.6 克隆值栈的顶部元素](/files/gstxBDWLA7rveJjT4nha)

`ROT_TWO()` 则可以交换栈中第一个和第二个值：

```c
    ROT_TWO();
```

此操作将切换第一个值和第二个值的顺序：

![图9.4.7 值栈的元素交换](/files/hz8sQTZ9IzEffYER0yDJ)

## Stack Effects

每一个操作码都有预定义的**栈操作**，可以由 `Python/compile.c` 中的函数 `stack_effect()` 计算得到。这个函数会返回操作码执行后的值栈中元素数目的增量。

这个增量可能是正值、负值或 0。在执行操作码时，若 `stack_effect()` 返回值（例如 `+1`）与值栈中的增量不匹配，就会抛出一个异常。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hai-shi.gitbook.io/cpython-internals/9-evalutaion-loop/9.4-value-stack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.