内存管理

概述

Python 中的内存管理涉及一个包含所有 Python 对象和数据结构的私有堆。这个私有堆的管理由Python 内存管理器在内部确保。Python 内存管理器具有不同的组件，这些组件处理各种动态存储管理方面，例如共享、分段、预分配或缓存。

在最低级别，一个原始内存分配器通过与操作系统内存管理器交互来确保私有堆中有足够的空间来存储所有与 Python 相关的数据。在原始内存分配器之上，几个特定于对象的分配器在同一个堆上运行，并实现适应每个对象类型特性的不同内存管理策略。例如，整数对象在堆中的管理方式与字符串、元组或字典不同，因为整数意味着不同的存储需求和速度/空间权衡。因此，Python 内存管理器将一些工作委托给特定于对象的分配器，但确保后者在私有堆的范围内运行。

重要的是要理解，Python 堆的管理是由解释器本身执行的，用户无法控制它，即使他们定期操作指向该堆内内存块的对象指针。Python 对象和其他内部缓冲区的堆空间分配是由 Python 内存管理器通过本文档中列出的 Python/C API 函数按需执行的。

为了避免内存损坏，扩展编写者不应尝试使用 C 库导出的函数来操作 Python 对象：malloc()、calloc()、realloc() 和 free()。这将导致 C 分配器和 Python 内存管理器之间的混合调用，并产生致命后果，因为它们实现不同的算法并在不同的堆上运行。但是，可以安全地使用 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 内存管理器只参与返回结果的字节对象的分配。

但是，在大多数情况下，建议从 Python 堆分配内存，特别是因为后者受 Python 内存管理器的控制。例如，当用 C 编写的新的对象类型扩展解释器时，这是必需的。使用 Python 堆的另一个原因是希望通知 Python 内存管理器扩展模块的内存需求。即使请求的内存专门用于内部、高度特定的目的，将所有内存请求委托给 Python 内存管理器也会使解释器对整个内存占用量有一个更准确的图像。因此，在某些情况下，Python 内存管理器可能会或可能不会触发适当的操作，例如垃圾回收、内存压缩或其他预防性程序。请注意，通过使用 C 库分配器（如上例所示），为 I/O 缓冲区分配的内存完全逃脱了 Python 内存管理器。

另请参阅

The PYTHONMALLOC 环境变量可用于配置 Python 使用的内存分配器。

环境变量 PYTHONMALLOCSTATS 可用于在每次创建新的 pymalloc 对象区域时以及在关闭时打印 pymalloc 内存分配器 的统计信息。

分配器域

所有分配函数都属于三个不同的“域”之一（另请参见 PyMemAllocatorDomain）。这些域代表不同的分配策略，并针对不同的目的进行了优化。每个域如何分配内存或每个域调用哪些内部函数的具体细节被认为是实现细节，但出于调试目的，可以在 此处 找到一个简化的表格。没有硬性要求仅将属于给定域的分配函数返回的内存用于该域暗示的目的（尽管这是推荐的做法）。例如，可以使用 PyMem_RawMalloc() 返回的内存来分配 Python 对象，或者使用 PyObject_Malloc() 返回的内存来分配缓冲区的内存。

三个分配域是

• 原始域：用于分配通用内存缓冲区的内存，其中分配必须转到系统分配器，或者分配器可以在没有 GIL 的情况下运行。内存直接从系统请求。

• “Mem”域：用于分配 Python 缓冲区和通用内存缓冲区的内存，其中分配必须在持有 GIL 的情况下执行。内存取自 Python 私有堆。

• 对象域：用于分配属于 Python 对象的内存。内存取自 Python 私有堆。

当释放先前由属于给定域的分配函数分配的内存时，必须使用匹配的特定释放函数。例如，必须使用 PyMem_Free() 来释放使用 PyMem_Malloc() 分配的内存。

原始内存接口

以下函数集是对系统分配器的包装器。这些函数是线程安全的，不需要持有 GIL。

默认原始内存分配器 使用以下函数：malloc()、calloc()、realloc() 和 free()；在请求零字节时调用 malloc(1)（或 calloc(1, 1)）。

在 3.4 版中添加。

void *PyMem_RawMalloc(size_t n)

分配 n 字节并返回指向分配内存的 void* 类型的指针，如果请求失败则返回 NULL。

如果可能，请求零字节将返回一个不同的非 NULL 指针，就像调用了 PyMem_RawMalloc(1) 一样。内存不会以任何方式初始化。

void *PyMem_RawCalloc(size_t nelem, size_t elsize)

分配nelem个元素，每个元素的大小（以字节为单位）为elsize，并返回指向已分配内存的类型为void*的指针，如果请求失败，则返回NULL。内存初始化为零。

如果请求零个元素或大小为零字节的元素，则如果可能，将返回一个不同的非NULL指针，就像调用了PyMem_RawCalloc(1, 1)一样。

在版本 3.5 中添加。

void *PyMem_RawRealloc(void *p, size_t n)

将p指向的内存块的大小调整为n字节。内容将保持不变，直到旧大小和新大小的最小值。

如果p为NULL，则该调用等效于PyMem_RawMalloc(n)；否则，如果n等于零，则内存块将被调整大小，但不会被释放，并且返回的指针是非NULL。

除非p为NULL，否则它必须由之前对PyMem_RawMalloc()、PyMem_RawRealloc()或PyMem_RawCalloc()的调用返回。

如果请求失败，PyMem_RawRealloc()将返回NULL，并且p将仍然是先前内存区域的有效指针。

void PyMem_RawFree(void *p)

释放p指向的内存块，该内存块必须由之前对PyMem_RawMalloc()、PyMem_RawRealloc()或PyMem_RawCalloc()的调用返回。否则，或者如果之前已经调用了PyMem_RawFree(p)，则会发生未定义的行为。

如果p为NULL，则不执行任何操作。

内存接口

以下函数集，模仿 ANSI C 标准，但指定了请求零字节时的行为，可用于从 Python 堆分配和释放内存。

默认内存分配器使用pymalloc 内存分配器。

警告

使用这些函数时，必须持有GIL。

在版本 3.6 中更改： 默认分配器现在是 pymalloc，而不是系统 malloc()。

void *PyMem_Malloc(size_t n)

是 稳定 ABI 的一部分。

分配 n 字节并返回指向分配内存的 void* 类型的指针，如果请求失败则返回 NULL。

如果可能，请求零字节将返回一个不同的非 NULL 指针，就像调用了 PyMem_Malloc(1) 一样。内存不会以任何方式初始化。

void *PyMem_Calloc(size_t nelem, size_t elsize)

自版本 3.7 起，是 稳定 ABI 的一部分。

分配nelem个元素，每个元素的大小（以字节为单位）为elsize，并返回指向已分配内存的类型为void*的指针，如果请求失败，则返回NULL。内存初始化为零。

如果可能，请求零个元素或大小为零字节的元素将返回一个不同的非 NULL 指针，就像调用了 PyMem_Calloc(1, 1) 一样。

在版本 3.5 中添加。

void *PyMem_Realloc(void *p, size_t n)

是 稳定 ABI 的一部分。

将p指向的内存块的大小调整为n字节。内容将保持不变，直到旧大小和新大小的最小值。

如果 p 为 NULL，则该调用等效于 PyMem_Malloc(n)；否则，如果 n 等于零，则内存块将被调整大小，但不会被释放，并且返回的指针将是非 NULL。

除非 p 为 NULL，否则它必须由之前对 PyMem_Malloc()、PyMem_Realloc() 或 PyMem_Calloc() 的调用返回。

如果请求失败，PyMem_Realloc() 将返回 NULL，并且 p 仍然是先前内存区域的有效指针。

void PyMem_Free(void *p)

是 稳定 ABI 的一部分。

释放 p 指向的内存块，该内存块必须由之前对 PyMem_Malloc()、PyMem_Realloc() 或 PyMem_Calloc() 的调用返回。否则，或者如果之前已经调用了 PyMem_Free(p)，则会发生未定义的行为。

如果p为NULL，则不执行任何操作。

为了方便起见，提供了以下面向类型的宏。请注意，TYPE 指的是任何 C 类型。

PyMem_New(TYPE, n)

与 PyMem_Malloc() 相同，但分配 (n * sizeof(TYPE)) 字节的内存。返回一个强制转换为 TYPE* 的指针。内存不会以任何方式初始化。

PyMem_Resize(p, TYPE, n)

与 PyMem_Realloc() 相同，但内存块的大小调整为 (n * sizeof(TYPE)) 字节。返回一个指向 TYPE* 的指针。返回时，p 将指向新的内存区域，如果失败则为 NULL。

这是一个 C 预处理器宏；p 始终被重新分配。保存 p 的原始值以避免在处理错误时丢失内存。

void PyMem_Del(void *p)

与 PyMem_Free() 相同。

此外，还提供以下宏集用于直接调用 Python 内存分配器，而无需涉及上面列出的 C API 函数。但是，请注意，它们的使用不会跨 Python 版本保持二进制兼容性，因此在扩展模块中已弃用。

• PyMem_MALLOC(size)

• PyMem_NEW(type, size)

• PyMem_REALLOC(ptr, size)

• PyMem_RESIZE(ptr, type, size)

• PyMem_FREE(ptr)

• PyMem_DEL(ptr)

对象分配器

以下函数集，模仿 ANSI C 标准，但指定了请求零字节时的行为，可用于从 Python 堆分配和释放内存。

注意

不能保证通过这些分配器返回的内存可以在拦截此域中的分配函数时成功转换为 Python 对象，方法是在 Customize Memory Allocators 部分中描述的。

默认对象分配器 使用 pymalloc 内存分配器。

警告

使用这些函数时，必须持有GIL。

void *PyObject_Malloc(size_t n)

是 稳定 ABI 的一部分。

分配 n 字节并返回指向分配内存的 void* 类型的指针，如果请求失败则返回 NULL。

如果可能，请求零字节将返回一个不同的非 NULL 指针，就像调用了 PyObject_Malloc(1) 一样。内存不会以任何方式初始化。

void *PyObject_Calloc(size_t nelem, size_t elsize)

自版本 3.7 起，是 稳定 ABI 的一部分。

分配nelem个元素，每个元素的大小（以字节为单位）为elsize，并返回指向已分配内存的类型为void*的指针，如果请求失败，则返回NULL。内存初始化为零。

如果可能，请求零个元素或大小为零字节的元素将返回一个不同的非 NULL 指针，就像调用了 PyObject_Calloc(1, 1) 一样。

在版本 3.5 中添加。

void *PyObject_Realloc(void *p, size_t n)

是 稳定 ABI 的一部分。

将p指向的内存块的大小调整为n字节。内容将保持不变，直到旧大小和新大小的最小值。

如果 p 为 NULL，则该调用等效于 PyObject_Malloc(n)；否则，如果 n 等于零，则内存块将被调整大小，但不会被释放，并且返回的指针将不为 NULL。

除非 p 为 NULL，否则它必须由之前对 PyObject_Malloc()、PyObject_Realloc() 或 PyObject_Calloc() 的调用返回。

如果请求失败，PyObject_Realloc() 将返回 NULL，并且 p 将仍然是先前内存区域的有效指针。

void PyObject_Free(void *p)

是 稳定 ABI 的一部分。

释放 p 指向的内存块，该内存块必须由之前对 PyObject_Malloc()、PyObject_Realloc() 或 PyObject_Calloc() 的调用返回。否则，或者如果 PyObject_Free(p) 之前已被调用，则会发生未定义的行为。

如果p为NULL，则不执行任何操作。

默认内存分配器

默认内存分配器

配置	名称	PyMem_RawMalloc	PyMem_Malloc	PyObject_Malloc
发布版本	"pymalloc"	malloc	pymalloc	pymalloc
调试版本	"pymalloc_debug"	malloc + 调试	pymalloc + 调试	pymalloc + 调试
发布版本，没有 pymalloc	"malloc"	malloc	malloc	malloc
调试版本，没有 pymalloc	"malloc_debug"	malloc + 调试	malloc + 调试	malloc + 调试

图例

• 名称：PYTHONMALLOC 环境变量的值。

• malloc：来自标准 C 库的系统分配器，C 函数：malloc()、calloc()、realloc() 和 free()。

• pymalloc：pymalloc 内存分配器.

• “+ 调试”：在 Python 内存分配器上的调试钩子。

• “调试版本”：调试模式下的 Python 构建.

自定义内存分配器

在 3.4 版中添加。

type PyMemAllocatorEx

用于描述内存块分配器的结构。该结构具有以下字段

字段	含义
void *ctx	作为第一个参数传递的用户上下文
void* malloc(void *ctx, size_t size)	分配一个内存块
void* calloc(void *ctx, size_t nelem, size_t elsize)	分配一个用零初始化的内存块
void* realloc(void *ctx, void *ptr, size_t new_size)	分配或调整内存块的大小
void free(void *ctx, void *ptr)	释放内存块

在 3.5 版本中更改: The PyMemAllocator 结构被重命名为 PyMemAllocatorEx 并添加了一个新的 calloc 字段。

type PyMemAllocatorDomain

用于标识分配器域的枚举。域

PYMEM_DOMAIN_RAW

函数

• PyMem_RawMalloc()

• PyMem_RawRealloc()

• PyMem_RawCalloc()

• PyMem_RawFree()

PYMEM_DOMAIN_MEM

函数

• PyMem_Malloc(),

• PyMem_Realloc()

• PyMem_Calloc()

• PyMem_Free()

PYMEM_DOMAIN_OBJ

函数

• PyObject_Malloc()

• PyObject_Realloc()

• PyObject_Calloc()

• PyObject_Free()

void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

获取指定域的内存块分配器。

void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

设置指定域的内存块分配器。

新的分配器在请求零字节时必须返回一个不同的非-NULL 指针。

对于 PYMEM_DOMAIN_RAW 域，分配器必须是线程安全的：当调用分配器时，GIL 不会被持有。

对于其余域，分配器也必须是线程安全的：分配器可以在不共享 GIL 的不同解释器中调用。

如果新的分配器不是钩子（不调用之前的分配器），则必须调用 PyMem_SetupDebugHooks() 函数，以便在新的分配器之上重新安装调试钩子。

另请参见 PyPreConfig.allocator 和 使用 PyPreConfig 预初始化 Python.

警告

PyMem_SetAllocator() 确实具有以下契约

• 它可以在 Py_PreInitialize() 之后和 Py_InitializeFromConfig() 之前调用，以安装自定义内存分配器。除了域强加的限制之外，对安装的分配器没有其他限制（例如，Raw 域允许在不持有 GIL 的情况下调用分配器）。有关更多信息，请参见 分配器域部分。

• 如果在 Python 完成初始化后调用（在调用 Py_InitializeFromConfig() 之后），分配器 **必须** 包装现有的分配器。将当前分配器替换为其他任意分配器 **不受支持**。

3.12 版本变更: 所有分配器必须是线程安全的。

void PyMem_SetupDebugHooks(void)

设置 Python 内存分配器中的调试钩子 以检测内存错误。

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

当 Python 在调试模式下构建 时，PyMem_SetupDebugHooks() 函数在 Python 预初始化 时被调用，以在 Python 内存分配器上设置调试钩子，以检测内存错误。

可以使用 PYTHONMALLOC 环境变量在以发布模式编译的 Python 上安装调试钩子（例如：PYTHONMALLOC=debug）。

可以在调用 PyMem_SetAllocator() 后使用 PyMem_SetupDebugHooks() 函数设置调试钩子。

这些调试钩子使用特殊的、可识别的位模式填充动态分配的内存块。新分配的内存填充字节 0xCD (PYMEM_CLEANBYTE)，释放的内存填充字节 0xDD (PYMEM_DEADBYTE)。内存块周围是“禁止字节”，填充字节 0xFD (PYMEM_FORBIDDENBYTE)。这些字节的字符串不太可能是有效的地址、浮点数或 ASCII 字符串。

运行时检查

• 检测 API 违规。例如，检测是否在由 PyMem_Malloc() 分配的内存块上调用了 PyObject_Free()。

• 检测缓冲区开始之前的写入（缓冲区下溢）。

• 检测缓冲区结束之后的写入（缓冲区溢出）。

• 检查在调用 PYMEM_DOMAIN_OBJ（例如：PyObject_Malloc()）和 PYMEM_DOMAIN_MEM（例如：PyMem_Malloc()）域的分配器函数时，是否持有 GIL。

发生错误时，调试钩子使用 tracemalloc 模块获取分配内存块的回溯。只有当 tracemalloc 正在跟踪 Python 内存分配并且内存块被跟踪时，才会显示回溯。

令 S = sizeof(size_t)。每个请求的 N 字节块的两端都会添加 2*S 字节。内存布局如下所示，其中 p 表示由类似 malloc 或 realloc 的函数返回的地址（p[i:j] 表示从 *(p+i)（包含）到 *(p+j)（不包含）的字节切片；请注意，负索引的处理方式与 Python 切片不同）。

p[-2*S:-S]

最初请求的字节数。这是一个 size_t，大端序（在内存转储中更容易阅读）。

p[-S]

API 标识符（ASCII 字符）

• 'r' 用于 PYMEM_DOMAIN_RAW。

• 'm' 用于 PYMEM_DOMAIN_MEM。

• 'o' 用于 PYMEM_DOMAIN_OBJ。

p[-S+1:0]

PYMEM_FORBIDDENBYTE 的副本。用于捕获下溢写和读取。

p[0:N]

请求的内存，填充了 PYMEM_CLEANBYTE 的副本，用于捕获对未初始化内存的引用。当调用类似 realloc 的函数请求更大的内存块时，新的多余字节也会填充 PYMEM_CLEANBYTE。当调用类似 free 的函数时，这些字节会被覆盖为 PYMEM_DEADBYTE，以捕获对已释放内存的引用。当调用类似 realloc 的函数请求更小的内存块时，多余的旧字节也会填充 PYMEM_DEADBYTE。

p[N:N+S]

PYMEM_FORBIDDENBYTE 的副本。用于捕获上溢写和读取。

p[N+S:N+2*S]

仅在定义了 PYMEM_DEBUG_SERIALNO 宏时使用（默认情况下未定义）。

一个序列号，在每次调用类似 malloc 或 realloc 的函数时递增 1。大端序 size_t。如果稍后检测到“错误内存”，序列号提供了一种极好的方法来在下次运行时设置断点，以捕获传递此块的瞬间。obmalloc.c 中的静态函数 bumpserialno() 是唯一递增序列号的地方，它存在是为了让你能够轻松地设置这样的断点。

类似 realloc 或 free 的函数首先检查每端 PYMEM_FORBIDDENBYTE 字节是否完好无损。如果它们被修改，诊断输出将写入 stderr，程序将通过 Py_FatalError() 终止。另一个主要故障模式是在程序读取其中一个特殊位模式并尝试将其用作地址时引发内存错误。如果你在调试器中看到这种情况，并且查看了该对象，你可能会看到它完全填充了 PYMEM_DEADBYTE（表示已释放的内存正在使用）或 PYMEM_CLEANBYTE（表示未初始化的内存正在使用）。

在 3.6 版中变更: 现在，PyMem_SetupDebugHooks() 函数也适用于在发布模式下编译的 Python。发生错误时，调试钩子现在使用 tracemalloc 获取分配内存块的回溯。调试钩子现在还检查在调用 PYMEM_DOMAIN_OBJ 和 PYMEM_DOMAIN_MEM 域的函数时是否持有 GIL。

在 3.8 版中变更: 字节模式 0xCB (PYMEM_CLEANBYTE)、0xDB (PYMEM_DEADBYTE) 和 0xFB (PYMEM_FORBIDDENBYTE) 已被替换为 0xCD、0xDD 和 0xFD，以使用与 Windows CRT 调试 malloc() 和 free() 相同的值。

pymalloc 分配器

Python 拥有一个名为 pymalloc 的分配器，它针对生命周期较短的小对象（小于或等于 512 字节）进行了优化。它使用称为“区域”的内存映射，在 32 位平台上固定大小为 256 KiB，在 64 位平台上固定大小为 1 MiB。对于大于 512 字节的分配，它会回退到 PyMem_RawMalloc() 和 PyMem_RawRealloc()。

pymalloc 是 默认分配器 的 PYMEM_DOMAIN_MEM（例如：PyMem_Malloc()）和 PYMEM_DOMAIN_OBJ（例如：PyObject_Malloc()）域。

区域分配器使用以下函数

• VirtualAlloc() 和 VirtualFree() 在 Windows 上，

• mmap() 和 munmap() 如果可用，

• malloc() 和 free() 否则。

如果 Python 使用 --without-pymalloc 选项配置，则此分配器将被禁用。它也可以使用 PYTHONMALLOC 环境变量在运行时禁用（例如：PYTHONMALLOC=malloc）。

自定义 pymalloc 区域分配器

在 3.4 版中添加。

type PyObjectArenaAllocator

用于描述区域分配器的结构。该结构具有三个字段

字段	含义
void *ctx	作为第一个参数传递的用户上下文
void* alloc(void *ctx, size_t size)	分配大小为 size 字节的区域
void free(void *ctx, void *ptr, size_t size)	释放区域

void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)

获取区域分配器。

void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)

设置区域分配器。

tracemalloc C API

在 3.7 版本中添加。

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

在 tracemalloc 模块中跟踪已分配的内存块。

成功时返回 0，错误时返回 -1（无法分配内存来存储跟踪信息）。如果 tracemalloc 被禁用，则返回 -2。

如果内存块已被跟踪，则更新现有的跟踪信息。

int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)

在 tracemalloc 模块中取消跟踪已分配的内存块。如果该块未被跟踪，则不执行任何操作。

如果 tracemalloc 被禁用，则返回 -2，否则返回 0。

示例

以下是第 概述 节中的示例，使用第一组函数集，重写为从 Python 堆分配 I/O 缓冲区。

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_Del(buf); /* allocated with PyMem_New */
return res;

请注意，在上面的两个示例中，缓冲区始终通过属于同一组的函数进行操作。实际上，对于给定的内存块，需要使用相同的内存 API 族，这样可以最大程度地降低混合不同分配器的风险。以下代码序列包含两个错误，其中一个被标记为致命，因为它混合了在不同堆上操作的两个不同的分配器。

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_Del()  */

除了用于处理来自 Python 堆的原始内存块的函数外，Python 中的对象还使用 PyObject_New、PyObject_NewVar 和 PyObject_Del() 进行分配和释放。

这些将在下一章中解释，该章介绍如何在 C 中定义和实现新的对象类型。