解密 Python 元组的实现原理

// Include/cpython/tupleobject.h
typedef struct {
    PyObject_VAR_HEAD
    PyObject *ob_item[1];
} PyTupleObject;

// Objects/tupleobject.c
PyObject *
PyTuple_New(Py_ssize_t size)
{
    // 参数 size 表示元组的长度
    PyTupleObject *op;
    // 如果 size 为 0，返回空数组
    if (size == 0) {
        return tuple_get_empty();
    }
    // 调用 tuple_alloc 为元组申请内存
    op = tuple_alloc(size);
    // 如果返回的指针为 NULL，表示申请失败
    if (op == NULL) {
        return NULL;
    }
    // 将指针数组中所有元素设置为 NULL
    for (Py_ssize_t i = 0; i < size; i++) {
        op->ob_item[i] = NULL;
    }
    // 让 GC 进行跟踪
    _PyObject_GC_TRACK(op);
    // 转成泛型指针之后返回
    return (PyObject *) op;
}

// Objects/tupleobject.c
static PyTupleObject *
tuple_alloc(Py_ssize_t size)
{
    // size 必须大于等于 0
    if (size < 0) {
        PyErr_BadInternalCall();
        return NULL;
    }
    // 优先从缓存池中获取，所以元组也有缓存池
    // 关于元组的缓存池稍后再聊
    PyTupleObject *op = maybe_freelist_pop(size);
    // 如果 op 为 NULL，说明缓存池无可用元素
    if (op == NULL) {
        // size * sizeof(PyObject *) + sizeof(PyTupleObject) 便是元组大小
        // 该值不能超过 PY_SSIZE_T_MAX，否则报错
        if ((size_t)size > ((size_t)PY_SSIZE_T_MAX - (sizeof(PyTupleObject) -
                    sizeof(PyObject *))) / sizeof(PyObject *)) {
            return (PyTupleObject *)PyErr_NoMemory();
        }
        // 为 PyTupleObject 和长度为 size 的指针数组申请内存
        // 然后将它的类型设置为 &PyTuple_Type，将 ob_size 设置为 size
        op = PyObject_GC_NewVar(PyTupleObject, &PyTuple_Type, size);
        if (op == NULL)
            return NULL;
    }
    // 返回 op
    return op;
}

// Include/internal/pycore_tuple.h
#define PyTuple_MAXSAVESIZE 20
#define PyTuple_NFREELISTS PyTuple_MAXSAVESIZE
#define PyTuple_MAXFREELIST 2000

struct _Py_tuple_state {
    PyTupleObject *free_list[PyTuple_NFREELISTS];
    int numfree[PyTuple_NFREELISTS];
};

// Objects/tupleobject.c
static void
tupledealloc(PyTupleObject *op)
{   
    // 缓存池存放的是长度为 1 ~ 20 的元组
    // 如果是空元组，那么它是单例的永恒对象，会永远存在
    // 因此这里会直接返回，不做任何额外操作
    if (Py_SIZE(op) == 0) {
        if (op == &_Py_SINGLETON(tuple_empty)) {
            return;
    }
    // 让 GC 不再跟踪
    PyObject_GC_UnTrack(op);
    // 延迟释放，和列表是类似的
    Py_TRASHCAN_BEGIN(op, tupledealloc)
    // 获取销毁的元组的长度
    Py_ssize_t i = Py_SIZE(op);
    // 减少内部元素指向对象的引用计数，因为元组不再持有对它们的引用
    while (--i >= 0) {
        Py_XDECREF(op->ob_item[i]);
    }
    // 尝试放入缓存池
    if (!maybe_freelist_push(op)) {
        // 如果元组长度大于 20，或者缓存池已满
        // 那么释放内存
        Py_TYPE(op)->tp_free((PyObject *)op);
    }

    Py_TRASHCAN_END
}

/* 在前面的章节中我们说了，在 3.12 之前
   对象的缓存池是以静态全局变量的形式定义在文件中，以 3.8 的元组缓存池为例
   static PyTupleObject *free_list[PyTuple_MAXSAVESIZE];
   static int numfree[PyTuple_MAXSAVESIZE];
   但在 3.12 的时候则被封装在了一个结构体（_Py_tuple_state）中
   在解释器启动之后会静态初始化好，并绑定在进程状态对象上面 */
// 所以这里的 STATE 便负责获取元组的缓存池，即 _Py_tuple_state 结构体实例
// 它里面包含了 numfree 和 free_list
#define STATE (interp->tuple)

// 将元组放入缓存池
static inline int
maybe_freelist_push(PyTupleObject *op)
{
#if PyTuple_NFREELISTS > 0
    // 获取进程状态对象，interp->tuple 便是元组的缓存池
    PyInterpreterState *interp = _PyInterpreterState_GET();
    // 如果元组长度为 0，不做处理
    if (Py_SIZE(op) == 0) {
        return0;
    }
    // free_list 里面的每个元素都指向了一个链表的头结点
    // 每条链表存放的元组都具有相同的长度，如果元组长度为 n
    // 那么它会放在 free_list[n - 1] 对应的链表中
    Py_ssize_t index = Py_SIZE(op) - 1;
    // index 必须小于 20，即元组长度不超过 20
    // STATE.numfree[index] 必须小于 2000，即每条链表最多缓存 2000 个元组
    if (index < PyTuple_NFREELISTS
        && STATE.numfree[index] < PyTuple_MAXFREELIST
        && Py_IS_TYPE(op, &PyTuple_Type))
    {
        // ob_item[0] 充当了链表的 next 指针
        // 这里让 op->ob_item[0] 等于 free_list[index]
        // 然后让 free_list[index] 等于 op
        // 这样元组就缓存起来了，并成为链表新的头结点，即 free_list[index]
        op->ob_item[0] = (PyObject *) STATE.free_list[index];
        STATE.free_list[index] = op;
        // 然后维护一下链表的节点个数
        STATE.numfree[index]++;
        OBJECT_STAT_INC(to_freelist);
        return1;
    }
#endif
    return0;
}

// Objects/tupleobject.c
static inline PyTupleObject *
maybe_freelist_pop(Py_ssize_t size)
{
#if PyTuple_NFREELISTS > 0
    // 获取进程状态对象
    PyInterpreterState *interp = _PyInterpreterState_GET();
    // size 不可能为 0
    // 如果 size 为 0，那么在 PyTuple_New 中会直接返回空元组
    if (size == 0) {
        return NULL;
    }
    assert(size > 0);
    // 缓存池中每个元素都指向一个链表的头结点
    // PyTuple_NFREELISTS 表示链表的个数，PyTuple_MAXSAVESIZE 表示缓存池的大小
    // 所以这两个宏是等价的，默认都是 20
    // 只有元组的长度不超过 20 的时候，才会被缓存
    if (size <= PyTuple_MAXSAVESIZE) {
        Py_ssize_t index = size - 1;
        // 获取链表的头节点
        PyTupleObject *op = STATE.free_list[index];
        if (op != NULL) {
            // 获取之后，它的下一个节点要成为新的头结点
            STATE.free_list[index] = (PyTupleObject *) op->ob_item[0];
            // 链表节点个数减 1
            STATE.numfree[index]--;
            // 增加引用计数之后返回
            _Py_NewReference((PyObject *)op);
            OBJECT_STAT_INC(from_freelist);
            return op;
        }
    }
#endif
    return NULL;
}

a, b, c, d = 1, 2, 3, 4

from timeit import timeit

t1 = timeit(stmt="x1 = [1, 2, 3, 4, 5]", number=1000000)
t2 = timeit(stmt="x2 = (1, 2, 3, 4, 5)", number=1000000)

print(round(t1, 2))  # 0.05
print(round(t2, 2))  # 0.01

// Objects/tupleobject.c
static inline PyObject *
tuple_get_empty(void)
{
    return Py_NewRef(&_Py_SINGLETON(tuple_empty));
}

// Include/internal/pycore_global_objects.h
struct _Py_static_objects {
    struct {
        // ...
        PyTupleObject tuple_empty;
        // ...
    } singletons;
};

// Include/internal/pycore_runtime_init.h
#define _PyRuntimeState_INIT(runtime) \
    { \
        .static_objects = { \
            .singletons = { \
             /* ... */ \
                .tuple_empty = { \
                    .ob_base = _PyVarObject_HEAD_INIT(&PyTuple_Type, 0) \
                }, \
                /* ... */ \
            }, \
        }, \
    }