CPython 内存管理详解：私堆架构、三域分配器 API 与 pymalloc/mimalloc 底层原理

本文基于 CPython 官方文档 Doc/c-api/memory.rst 展开，系统讲解 Python/C API 中的内存管理机制：私堆（private heap）的分层设计、Raw/Mem/Object 三个分配器域的 API 语义与零字节边界行为、默认分配器（pymalloc、mimalloc）的 arena 原理与可定制钩子（PyMem_SetAllocator、调试钩子位模式），并结合 CPython 源码印证 PYTHONMALLOC 环境变量解析与 pymalloc 的实现细节。读完本文，你能够正确选用 CPython 三组内存分配 API、避免与系统 malloc/free 混用导致的堆错乱，并能在扩展模块中定制或诊断 Python 内存分配器。

一、Python 私堆与内存管理器总览

Python 的内存管理围绕一个包含所有 Python 对象与数据结构的**私堆（private heap）**展开。该私堆由解释器内部的 Python memory manager 管理，它由多个组件构成，分别负责共享、分段、预分配或缓存等动态存储管理职责。

整体分为两层：

• 最底层是原始内存分配器（raw memory allocator），通过与操作系统内存管理器交互，确保私堆中有足够空间存放所有 Python 相关数据；
• 其上是一组对象专用分配器（object-specific allocators），在同一私堆上运作，针对每种对象类型的特性实现不同的内存管理策略。例如整数对象与字符串、元组、字典的管理方式不同，因为它们的存储需求和速度/空间权衡各不相同。

文档特别强调两点实践约束：

1. 私堆由解释器自行管理，用户没有控制权。扩展模块虽频繁操作指向私堆内存块的对象指针，但堆空间的分配始终由 Python 内存管理器通过 C API 按需完成。
2. 绝不能用 C 库的 malloc/calloc/realloc/free 操作 Python 对象。C 分配器与 Python 内存管理器实现不同算法、操作不同堆，混用会引发灾难性后果。

但有一个合法例外：为独立用途（如 I/O 缓冲）使用 C 库分配器是安全的，官方示例如下：

PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyBytes_FromString(buf);
free(buf); /* malloc'ed */
return res;

在这个示例中，I/O 缓冲的内存请求由 C 库分配器处理；Python 内存管理器只参与了最终返回的 bytes 对象的分配。

不过多数情况下推荐使用 Python 堆分配，原因有二：

• 当用 C 扩展 Python、新增对象类型时，必须从 Python 堆分配；
• 把内存需求告知 Python 内存管理器，能使其对整个解释器内存占用有更准确的画像，从而在必要时触发垃圾回收、内存紧缩等预防性措施。相反，用 C 库分配器分配的 I/O 缓冲则完全逃离了 Python 内存管理器的视野。

相关环境变量（在 Python/initconfig.c 中解析）：

• PYTHONMALLOC：配置 Python 使用的内存分配器；
• PYTHONMALLOCSTATS：每次创建新的 pymalloc 对象 arena 以及解释器退出时，打印 pymalloc 分配器统计。从源码可见 Python/initconfig.c 中 config->malloc_stats = 1 的解析逻辑。

二、分配器域（Allocator Domains）：三套 API、三个策略

所有分配函数都归属于三个不同"域"（对应 C 类型 PyMemAllocatorDomain），每个域代表不同的分配策略。各域内部如何分配内存属于实现细节，文档中给出了一个简化对照表（见后文"默认内存分配器"一节）。铁律：分配和释放同一块内存的 API 必须来自同一域——例如用 PyMem_Malloc 分配的内存必须用 PyMem_Free 释放。

三个分配域：

域	用途	内存来源	线程状态要求
Raw 域	通用内存缓冲；要求必须走系统分配器、或可在无 attached thread state 时运行	直接向系统请求	不需要 attached thread state
Mem 域	Python 缓冲与通用缓冲；要求在有 attached thread state 时运行	Python 私堆	必须 attached thread state
Object 域	Python 对象	Python 私堆	必须 attached thread state

域枚举定义可在 Include/cpython/pymem.h 中确认：

typedef enum {
    /* PyMem_RawMalloc(), PyMem_RawRealloc() and PyMem_RawFree() */
    PYMEM_DOMAIN_RAW,
    /* PyMem_Malloc(), PyMem_Realloc() and PyMem_Free() */
    PYMEM_DOMAIN_MEM,
    /* PyObject_Malloc(), PyObject_Realloc() and PyObject_Free() */
    PYMEM_DOMAIN_OBJ
} PyMemAllocatorDomain;

文档还特别指出：free-threaded（无 GIL）构建对 Object 域的要求由"最佳实践"升级为硬约束——只有 Python 对象能用 Object 域分配，且所有 Python 对象必须用该域分配。例如缓冲（非 Python 对象）应用 PyMem_Malloc、PyMem_RawMalloc 或 malloc 分配，而不能用 PyObject_Malloc。

三、Raw 内存接口：系统分配器的线程安全封装

Raw 域函数集（3.4 起提供）是系统分配器的封装，线程安全，因此无需 attached thread state。默认原始分配器使用 malloc、calloc、realloc、free；请求 0 字节时等价于调用 malloc(1)（或 calloc(1, 1)）。

PyMem_RawMalloc

void* PyMem_RawMalloc(size_t n)

分配 n 字节，成功返回 void* 指针，失败返回 NULL。请求 0 字节时，若可能则返回一个非 NULL 的独立指针（相当于调用了 PyMem_RawMalloc(1)）。内存不会做任何初始化。

PyMem_RawCalloc

void* PyMem_RawCalloc(size_t nelem, size_t elsize)   /* 3.5 新增 */

分配 nelem 个各 elsize 字节的元素并清零。请求 0 个元素或 0 字节元素时，若可能返回非 NULL 指针（相当于 PyMem_RawCalloc(1, 1)）。

PyMem_RawRealloc

void* PyMem_RawRealloc(void *p, size_t n)

把 p 指向的块调整为 n 字节，内容在旧新尺寸的最小值内保持不变。边界语义：

• p 为 NULL 时等价于 PyMem_RawMalloc(n)；
• n 为 0 时，内存块被调整大小但不会释放，返回非 NULL 指针；
• p 若非 NULL，必须来自此前的 PyMem_RawMalloc、PyMem_RawRealloc 或 PyMem_RawCalloc；
• 失败时返回 NULL，且 p 仍是指向原内存区域的合法指针（不会丢失旧块）。

PyMem_RawFree

void PyMem_RawFree(void *p)

释放的块必须来自 PyMem_RawMalloc/PyMem_RawRealloc/PyMem_RawCalloc，否则或重复释放均为未定义行为。p 为 NULL 时不执行任何操作。

四、Mem 内存接口：从 Python 私堆分配缓冲

Mem 域函数集（PyMem_Malloc 等）仿照 ANSI C 标准，但明确规定了 0 字节请求的行为，用于从 Python 私堆分配与释放内存。

前置条件警告：调用这些函数时必须存在 attached thread state。

默认分配器随构建形态而变：

• GIL 启用构建（默认）：默认内存分配器为 pymalloc（3.6 起由系统 malloc 切换为 pymalloc）；
• free-threaded 构建：默认为 mimalloc（3.13 起）。

四个核心函数

• void* PyMem_Malloc(size_t n)：分配 n 字节；0 字节请求返回非 NULL 独立指针（相当于 PyMem_Malloc(1)）；内存不初始化。
• void* PyMem_Calloc(size_t nelem, size_t elsize)（3.5 新增）：分配 nelem × elsize 字节并清零；0 元素/0 字节元素返回非 NULL（相当于 PyMem_Calloc(1, 1)）。
• void* PyMem_Realloc(void *p, size_t n)：语义与 PyMem_RawRealloc 完全同构（NULL 入参等价于 PyMem_Malloc(n)；n=0 只缩小不释放；失败时原指针保持有效）。
• void PyMem_Free(void *p)：只允许释放来自 Mem 域三兄弟的块；NULL 为空操作。

类型导向便捷宏

• PyMem_New(TYPE, n)：等价 PyMem_Malloc，但分配 n * sizeof(TYPE) 字节，返回 TYPE*；不初始化内存。
• PyMem_Resize(p, TYPE, n)：等价 PyMem_Realloc，调整为 n * sizeof(TYPE) 字节并返回 TYPE*。这是预处理器宏，p 总是被重新赋值——出错时 p 变为 NULL，务必先保存 p 原值以避免丢失内存。
• PyMem_Del(void *p)：与 PyMem_Free 相同。

废弃别名

以下大写宏为软废弃（soft deprecated）别名，仅保留向后兼容（3.4 起成为对应函数的别名，保证二进制兼容；宏形式自 2.0 起标记为 deprecated）：

废弃别名	对应函数/宏
PyMem_MALLOC(size)	PyMem_Malloc
PyMem_NEW(type, size)	PyMem_New
PyMem_REALLOC(ptr, size)	PyMem_Realloc
PyMem_RESIZE(ptr, type, size)	PyMem_Resize
PyMem_FREE(ptr)	PyMem_Free
PyMem_DEL(ptr)	PyMem_Free

五、Object 分配器：Python 对象的分配与释放

Object 域函数集（PyObject_Malloc 等）同样仿照 ANSI C 标准并规定 0 字节行为，从 Python 私堆分配对象内存。默认分配器为 pymalloc；free-threaded 构建下默认为 mimalloc。同样要求 attached thread state。

一个实现细节值得注意：文档说明无法保证拦截 Object 域分配函数时，返回的内存能成功转型为 Python 对象。

• void* PyObject_Malloc(size_t n)：语义与 PyMem_Malloc 一致（0 字节返回非 NULL 独立指针、不初始化）。
• void* PyObject_Calloc(size_t nelem, size_t elsize)（3.5 新增）：清零分配，0 元素/0 字节元素返回非 NULL。
• void* PyObject_Realloc(void *p, size_t n)：语义与 PyMem_Realloc 同构。
• void PyObject_Free(void *p)：只允许释放 Object 域分配的块；NULL 为空操作。两个重要告诫：
  • 不要直接调用它释放对象内存，应调用类型的 tp_free 槽；
  • 不要用它释放 PyObject_GC_New/PyObject_GC_NewVar 分配的内存，应改用 PyObject_GC_Del。
  • 相关 API：PyObject_Malloc、PyObject_Realloc、PyObject_Calloc、PyObject_New、PyObject_NewVar、PyType_GenericAlloc、tp_free。

六、默认内存分配器对照表

不同构建形态下，三个域各自的默认分配器如下（"Name" 列为 PYTHONMALLOC 环境变量可取的值）：

配置	Name	PyMem_RawMalloc	PyMem_Malloc	PyObject_Malloc
Release 构建	"pymalloc"	malloc	pymalloc	pymalloc
Debug 构建	"pymalloc_debug"	malloc + debug	pymalloc + debug	pymalloc + debug
Release 构建、无 pymalloc	"malloc"	malloc	malloc	malloc
Debug 构建、无 pymalloc	"malloc_debug"	malloc + debug	malloc + debug	malloc + debug
Free-threaded 构建	"mimalloc"	mimalloc	mimalloc	mimalloc
Free-threaded debug 构建	"mimalloc_debug"	mimalloc + debug	mimalloc + debug	mimalloc + debug

图例：malloc 指 C 标准库系统分配器（malloc/calloc/realloc/free）；+ debug 表示叠加调试钩子；"Debug build" 指 Python 以调试模式构建。

分配器名称枚举（PyMemAllocatorName）可在 Include/cpython/pymem.h 中确认：PYMEM_ALLOCATOR_DEBUG、PYMEM_ALLOCATOR_MALLOC(_DEBUG)、PYMEM_ALLOCATOR_PYMALLOC(_DEBUG)（仅 WITH_PYMALLOC 时编译）、PYMEM_ALLOCATOR_MIMALLOC(_DEBUG)（仅 WITH_MIMALLOC 时编译）——源码与文档的构建条件开关一一对应。

七、定制内存分配器（Customize Memory Allocators）

（3.4 起提供）CPython 允许为每个域整体替换底层分配器。

PyMemAllocatorEx 结构体

描述一个内存块分配器的结构，包含用户上下文与四个函数指针：

字段	含义
void *ctx	作为第一参数传给各回调的用户上下文
void* (*malloc)(void *ctx, size_t size)	分配内存块
void* (*calloc)(void *ctx, size_t nelem, size_t elsize)	分配清零内存块（3.5 加入；3.5 前该结构名为 PyMemAllocator）
void* (*realloc)(void *ctx, void *ptr, size_t new_size)	分配或调整内存块
void (*free)(void *ctx, void *ptr)	释放内存块

结构体与域枚举的声明见 Include/cpython/pymem.h。

获取与设置分配器

void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator);
void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator);

PyMem_SetAllocator 的约束与契约：

• 新分配器请求 0 字节时必须返回非 NULL 的独立指针；
• Raw 域的分配器必须线程安全：调用它时没有 attached thread state；
• 其余域必须线程安全：分配器可能在不同解释器（不共享 GIL）中被并发调用（3.12 起要求所有分配器线程安全）；
• 若新分配器不是钩子（即不调用旧分配器），必须再调用 PyMem_SetupDebugHooks 在新分配器之上重装调试钩子；
• 另见 PyPreConfig.allocator 字段与 PyPreConfig 预初始化流程。

调用时机契约（官方 warning 级别）：

• 可以在 Py_PreInitialize 之后、Py_InitializeFromConfig 之前调用，用于安装自定义分配器。此时除域级约束外（如 Raw 域允许在无 attached thread state 时被调用）无其他限制；
• 若 Python 已完成初始化（Py_InitializeFromConfig 之后），新分配器必须包装现有分配器；直接替换为任意其他分配器是不受支持的。

八、Python 内存分配器上的调试钩子

当 Python 以调试模式构建时，PyMem_SetupDebugHooks 会在 Python 预初始化阶段被调用，为内存分配器安装调试钩子以捕获内存错误。Release 构建则可通过 PYTHONMALLOC=debug 安装钩子；PyMem_SetupDebugHooks 也可在 PyMem_SetAllocator 之后用于重装钩子。

调试钩子的工作原理是用特殊可辨识的位模式填充动态分配的内存块。特征字节定义于 Include/internal/pycore_pymem.h：

#define PYMEM_CLEANBYTE      0xCD   /* 新分配内存 */
#define PYMEM_DEADBYTE       0xDD   /* 已释放内存 */
#define PYMEM_FORBIDDENBYTE  0xFD   /* 块首尾的"禁区字节" */

这些字节串几乎不可能是合法的地址、浮点数或 ASCII 字符串。（3.8 起由 0xCB/0xDB/0xFB 改为 0xCD/0xDD/0xFD，与 Windows CRT 调试 malloc/free 取值一致。）

运行时检查项：

• 检测 API 违规（例如用 PyObject_Free 释放 PyMem_Malloc 分配的块）；
• 检测缓冲区下溢（写入缓冲区起点之前）；
• 检测缓冲区上溢（写入缓冲区终点之后）；
• 检查 PYMEM_DOMAIN_OBJ（如 PyObject_Malloc）与 PYMEM_DOMAIN_MEM（如 PyMem_Malloc）域的分配器函数被调用时存在 attached thread state（3.6 起加入）。

出错时，调试钩子借助 tracemalloc 模块获取内存块分配处的 traceback——仅当 tracemalloc 正在跟踪且该块被跟踪时才显示（3.6 起支持 Release 构建并用 tracemalloc 取 traceback）。

内存布局（设 S = sizeof(size_t)，每个 N 字节的请求块两端各附加 2*S 字节；p 为 malloc 类函数返回的地址）：

区域	内容
p[-2*S:-S]	原始请求字节数，size_t，大端（便于内存转储阅读）
p[-S]	API 标识符（ASCII）：Raw 域为 'r'、Mem 域为 'm'、Object 域为 'o'
p[-S+1:0]	PYMEM_FORBIDDENBYTE 副本，捕获写/读低于起点
p[0:N]	请求的内存，填充 PYMEM_CLEANBYTE，捕获对未初始化内存的引用；realloc 扩大时新增字节同样填充 CLEANBYTE；free 时覆写为 DEADBYTE（捕获对已释放内存的引用）；realloc 缩小时多余的旧字节也填 DEADBYTE
p[N:N+S]	PYMEM_FORBIDDENBYTE 副本，捕获写/读超出终点
p[N+S:N+2*S]	仅当定义 PYMEM_DEBUG_SERIALNO 宏（默认未定义）时启用：每次 malloc 类/realloc 类调用递增 1 的序号（大端 size_t）。检测到"坏内存"时可据此在下次运行中对 bumpserialno()（位于 Objects/obmalloc.c）下断点，精确捕获该块被交出的时刻

realloc 类或 free 类函数会先校验两端的 PYMEM_FORBIDDENBYTE 是否完好；若被改动，向 stderr 写诊断输出并通过 Py_FatalError() 终止程序。另一类典型故障是程序读到特殊位模式后试图把它当地址使用——此时在调试器中查看对象，通常会看到整块被 PYMEM_DEADBYTE（使用了已释放内存）或 PYMEM_CLEANBYTE（使用了未初始化内存）填满。

九、pymalloc 分配器：小对象 arena 策略

pymalloc 是为小对象（≤ 512 字节、短生命周期）优化的分配器，使用固定大小的内存映射单元 "arena"：

• 32 位平台 arena 为 256 KiB；
• 64 位平台 arena 为 1 MiB；
• 若以 --with-pymalloc-hugepages 配置 Python，64 位平台 arena 增大到 2 MiB 以匹配大页尺寸，arena 分配会尝试使用大页（Linux 为 MAP_HUGETLB、Windows 为 MEM_LARGE_PAGES），失败时自动回退到普通页。运行时环境变量 PYTHON_PYMALLOC_HUGEPAGES 的解析逻辑见 Python/initconfig.c。

超过 512 字节的分配回退到 PyMem_RawMalloc/PyMem_RawRealloc。pymalloc 是 PYMEM_DOMAIN_MEM（如 PyMem_Malloc）与 PYMEM_DOMAIN_OBJ（如 PyObject_Malloc）两个域的默认分配器。

arena 分配器跨平台的底层取页函数为：

• Windows 上 VirtualAlloc / VirtualFree；
• 可用时 mmap / munmap；
• 否则 malloc / free。

禁用方式有二：构建时用 --without-pymalloc；运行时用 PYTHONMALLOC=malloc。典型场景：用 AddressSanitizer（--with-address-sanitizer）构建 Python 时禁用 pymalloc，有助于暴露 C 代码中的底层 bug。

arena 管理实现集中在 Objects/obmalloc.c（以 WITH_PYMALLOC 宏条件编译，arena 状态与对象分配主逻辑在该文件的 #ifdef WITH_PYMALLOC 段落中）。

定制 pymalloc 的 arena 分配器

（3.4 起提供）可以用 PyObjectArenaAllocator 结构替换 arena 级取页函数：

字段	含义
void *ctx	用户上下文，作为第一参数传入
void* (*alloc)(void *ctx, size_t size)	分配 size 字节的 arena
void (*free)(void *ctx, void *ptr, size_t size)	释放 arena

配套 API：

void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator);
void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator);

PyObject_SetArenaAllocator 的实现在 Objects/obmalloc.c。

十、mimalloc 分配器：free-threaded 构建的默认与必选

（3.13 起加入）当底层平台支持时，CPython 集成微软的 mimalloc 通用分配器。与只优化 ≤ 512 字节小对象的 pymalloc 不同，mimalloc 处理任意大小的分配，具有优异的通用性能特征（最初由 Daan Leijen 为 Koka 与 Lean 语言的运行时开发）。

• free-threaded 构建：mimalloc 是 PYMEM_DOMAIN_MEM 与 PYMEM_DOMAIN_OBJ 域的默认且必需的分配器，不可禁用。free-threaded 构建使用每线程 mimalloc 堆，使大多数分配与释放操作无需加锁即可完成——这正是无 GIL 模型下高并发分配性能的关键。
• 默认（非 free-threaded）构建：mimalloc 可用但非默认，可用 PYTHONMALLOC=mimalloc（或 PYTHONMALLOC=mimalloc_debug 叠加调试钩子）在运行时启用；构建时可用 --without-mimalloc 禁用，但该选项不能与 --disable-gil 组合使用。

mimalloc 源码以 vendored 形式位于仓库的 Objects/mimalloc 目录。

十一、tracemalloc C API

（3.7 起提供）扩展模块中自行分配（例如用 Raw 域或 C 库分配器）的内存可手动接入 tracemalloc 的跟踪体系：

int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size);
int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr);

• PyTraceMalloc_Track：在 tracemalloc 中跟踪一个已分配块。成功返回 0；因存储 trace 所需内存分配失败时返回 -1；tracemalloc 被禁用时返回 -2。若块已被跟踪，则更新既有 trace。
• PyTraceMalloc_Untrack：取消跟踪。块未被跟踪时不做任何操作。tracemalloc 禁用时返回 -2，否则返回 0。

十二、实战示例：同一任务的两套写法和混用陷阱

官方文档最后给出了与总览一节对照的完整示例。把 I/O 缓冲改从 Python 私堆分配（Mem 域函数集）：

PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;

同样的代码，使用类型导向函数集：

PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_New */
return res;

注意两个示例中缓冲始终只通过同一函数集操作——对给定内存块必须使用同一 API 族，才能把混用不同分配器的风险降到最低。下面这段代码含两个错误，其中标 fatal 的一个混用了操作不同堆的两个分配器：

char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Free()  */

（严格说 PyMem_Del 与 PyMem_Free 等价、不算真正的错误，但官方示例以此强调"按域配对释放"的规范写法；真正的致命错误是用 free 释放私堆内存。）

在原始内存块 API 之外，Python 对象本身用 PyObject_New、PyObject_NewVar 与 PyObject_Free 分配和释放——对象类型的具体实现细节见 CPython 文档中定义与实现新 C 对象类型的后续章节。

附：本文涉及的仓库关键路径

路径	内容
Doc/c-api/memory.rst	本文主体对应的官方文档
Include/cpython/pymem.h	分配域枚举、PyMemAllocatorEx、Get/SetAllocator 声明
Include/internal/pycore_pymem.h	0xCD/0xDD/0xFD 调试特征字节定义
Python/initconfig.c	PYTHONMALLOC、PYTHONMALLOCSTATS、PYTHON_PYMALLOC_HUGEPAGES 环境变量解析
Objects/obmalloc.c	pymalloc arena 分配器与调试钩子的核心实现
Objects/mimalloc	vendored 的 mimalloc 源码

适用前提：以上 API 语义与默认分配器行为以本仓库当前 CPython 源码为准。涉及版本行为时注意关键节点——3.4 引入 Raw 域与 arena 定制 API；3.5 引入 Calloc 系列；3.6 起默认分配器切换为 pymalloc且调试钩子支持 Release 构建；3.12 起所有分配器必须线程安全；3.13 起 free-threaded 构建默认（并强制）使用 mimalloc。free-threaded 相关约束仅在无 GIL 构建下生效，常规 GIL 构建中 Object 域的使用约定仍是最佳实践。