缓冲区协议¶
Python 中的某些对象封装了对底层内存数组或缓冲区的访问。这些对象包括内置的 bytes
和 bytearray
,以及一些扩展类型,例如 array.array
。第三方库可以为特殊目的定义自己的类型,例如图像处理或数值分析。
虽然这些类型中的每一个都有自己的语义,但它们都具有由可能很大的内存缓冲区支持的共同特征。因此,在某些情况下,直接访问该缓冲区而无需中间复制是可取的。
Python 在 C 级别提供了这种功能,形式为 缓冲区协议。该协议有两面
在生产者方面,一个类型可以导出一个“缓冲区接口”,允许该类型的对象公开其底层缓冲区的信息。该接口在 缓冲区对象结构 部分进行了描述;
在消费者方面,可以使用多种方法来获取指向对象原始底层数据的指针(例如方法参数)。
诸如 bytes
和 bytearray
之类的简单对象以面向字节的形式公开其底层缓冲区。其他形式也是可能的;例如,由 array.array
公开的元素可以是多字节值。
缓冲区接口的一个示例消费者是文件对象的 write()
方法:任何可以通过缓冲区接口导出字节序列的对象都可以写入文件。虽然 write()
只需要对传递给它的对象的内部内容进行只读访问,但其他方法(例如 readinto()
)需要对参数的内容进行写访问。缓冲区接口允许对象选择性地允许或拒绝导出读写和只读缓冲区。
缓冲区接口的消费者可以通过两种方式获取目标对象的缓冲区
使用正确的参数调用
PyObject_GetBuffer()
;使用
y*
,w*
或s*
格式代码 之一调用PyArg_ParseTuple()
(或其兄弟函数之一)。
在这两种情况下,当不再需要缓冲区时,必须调用 PyBuffer_Release()
。如果未能这样做,可能会导致各种问题,例如资源泄漏。
缓冲区结构¶
缓冲区结构(或简称为“缓冲区”)是一种将另一个对象的二进制数据暴露给 Python 程序员的方式。它们也可以用作零拷贝切片机制。利用它们引用内存块的能力,可以非常轻松地将任何数据暴露给 Python 程序员。该内存可以是 C 扩展中的大型常量数组,可以是用于在传递给操作系统库之前进行操作的原始内存块,也可以用于以其本机内存格式传递结构化数据。
与 Python 解释器公开的大多数数据类型相反,缓冲区不是 PyObject
指针,而是简单的 C 结构。这使得它们可以非常简单地创建和复制。当需要围绕缓冲区的通用包装器时,可以创建一个 memoryview 对象。
有关如何编写导出对象的简短说明,请参阅 缓冲区对象结构。有关获取缓冲区的信息,请参阅 PyObject_GetBuffer()
.
-
type Py_buffer¶
- 自版本 3.11 起,它是 稳定 ABI 的一部分(包括所有成员)。
-
void *buf¶
指向缓冲区字段描述的逻辑结构的起始位置的指针。这可以是导出器底层物理内存块中的任何位置。例如,对于负
strides
,该值可能指向内存块的末尾。对于 连续 数组,该值指向内存块的开头。
-
PyObject *obj¶
对导出对象的新的引用。该引用由使用者拥有,并由
PyBuffer_Release()
自动释放(即引用计数递减)并设置为NULL
。该字段等效于任何标准 C-API 函数的返回值。作为特殊情况,对于由
PyMemoryView_FromBuffer()
或PyBuffer_FillInfo()
包装的临时缓冲区,此字段为NULL
。一般来说,导出对象 MUST NOT 使用此方案。
-
Py_ssize_t len¶
product(shape) * itemsize
。对于连续数组,这是底层内存块的长度。对于非连续数组,它是逻辑结构如果被复制到连续表示将具有的长度。仅当缓冲区是通过保证连续性的请求获得时,访问
((char *)buf)[0] up to ((char *)buf)[len-1]
才有效。在大多数情况下,此类请求将是PyBUF_SIMPLE
或PyBUF_WRITABLE
。
-
int readonly¶
指示缓冲区是否为只读。此字段由
PyBUF_WRITABLE
标志控制。
-
Py_ssize_t itemsize¶
单个元素的字节大小。与在非
NULL
format
值上调用的struct.calcsize()
的值相同。重要例外:如果使用者请求没有
PyBUF_FORMAT
标志的缓冲区,format
将被设置为NULL
,但itemsize
仍然具有原始格式的值。如果存在
shape
,则等式product(shape) * itemsize == len
仍然成立,使用者可以使用itemsize
导航缓冲区。如果
shape
由于PyBUF_SIMPLE
或PyBUF_WRITABLE
请求而为NULL
,使用者必须忽略itemsize
并假设itemsize == 1
。
-
char *format¶
一个以
struct
模块样式语法描述单个项目内容的以 NULL 结尾的字符串。如果这是NULL
,则假设为"B"
(无符号字节)。此字段由
PyBUF_FORMAT
标志控制。
-
int ndim¶
内存作为 n 维数组表示的维度数。如果为
0
,buf
指向单个项目,表示标量。在这种情况下,shape
、strides
和suboffsets
必须为NULL
。维度的最大数量由PyBUF_MAX_NDIM
给出。
-
Py_ssize_t *shape¶
一个长度为
ndim
的Py_ssize_t
数组,指示内存作为 n 维数组的形状。请注意,shape[0] * ... * shape[ndim-1] * itemsize
必须等于len
。形状值限制为
shape[n] >= 0
。情况shape[n] == 0
需要特别注意。有关更多信息,请参见 复杂数组。形状数组对于使用者是只读的。
-
Py_ssize_t *strides¶
一个长度为
ndim
的Py_ssize_t
数组,给出每个维度中要跳过的字节数以获取新元素。步长值可以是任何整数。对于常规数组,步长通常为正,但使用者必须能够处理
strides[n] <= 0
的情况。有关更多信息,请参见 复杂数组。步长数组对于使用者是只读的。
-
Py_ssize_t *suboffsets¶
一个长度为
ndim
的Py_ssize_t
数组。如果suboffsets[n] >= 0
,则沿第 n 维存储的值是指针,并且子偏移值指示在取消引用后为每个指针添加多少字节。子偏移值为负表示不应进行取消引用(在连续内存块中跨步)。如果所有子偏移量都为负(即不需要取消引用),则此字段必须为
NULL
(默认值)。这种类型的数组表示由 Python 图像库 (PIL) 使用。有关如何访问此类数组的元素的更多信息,请参见 复杂数组。
子偏移量数组对于使用者是只读的。
-
void *internal¶
此字段供导出对象内部使用。例如,导出器可以将其重新转换为整数,并用于存储有关在释放缓冲区时是否必须释放形状、步幅和子偏移量数组的标志。消费者绝对不能修改此值。
-
void *buf¶
常量
-
PyBUF_MAX_NDIM¶
内存表示的维度数的最大值。导出器必须遵守此限制,多维缓冲区的消费者应该能够处理最多
PyBUF_MAX_NDIM
个维度。当前设置为 64。
缓冲区请求类型¶
缓冲区通常通过向导出对象发送缓冲区请求来获取,方法是使用 PyObject_GetBuffer()
。由于内存逻辑结构的复杂性可能差异很大,因此消费者使用 flags 参数来指定它可以处理的精确缓冲区类型。
所有 Py_buffer
字段都由请求类型明确定义。
与请求无关的字段¶
只读、格式¶
PyBUF_WRITABLE
可以与下一节中的任何标志进行 |’d 操作。由于 PyBUF_SIMPLE
定义为 0,因此 PyBUF_WRITABLE
可以用作独立标志来请求简单的可写缓冲区。
PyBUF_FORMAT
可以与除 PyBUF_SIMPLE
之外的任何标志进行“或”运算。后者已经隐含了格式 B
(无符号字节)。
形状、步长、子偏移量¶
控制内存逻辑结构的标志按复杂度降序排列。请注意,每个标志包含其下方标志的所有位。
请求 |
形状 |
步长 |
子偏移量 |
---|---|---|---|
|
是 |
是 |
如果需要 |
|
是 |
是 |
NULL |
|
是 |
NULL |
NULL |
|
NULL |
NULL |
NULL |
连续性请求¶
可以显式请求 C 或 Fortran 连续性,并带有或不带有步长信息。如果没有步长信息,缓冲区必须是 C 连续的。
请求 |
形状 |
步长 |
子偏移量 |
连续 |
---|---|---|---|---|
|
是 |
是 |
NULL |
C |
|
是 |
是 |
NULL |
F |
|
是 |
是 |
NULL |
C 或 F |
是 |
NULL |
NULL |
C |
复合请求¶
所有可能的请求都由上一节中标志的某种组合完全定义。为了方便起见,缓冲区协议将常用组合作为单个标志提供。
在下表中,U 代表未定义的连续性。使用者必须调用 PyBuffer_IsContiguous()
来确定连续性。
请求 |
形状 |
步长 |
子偏移量 |
连续 |
只读 |
格式 |
---|---|---|---|---|---|---|
|
是 |
是 |
如果需要 |
U |
0 |
是 |
|
是 |
是 |
如果需要 |
U |
1 或 0 |
是 |
|
是 |
是 |
NULL |
U |
0 |
是 |
|
是 |
是 |
NULL |
U |
1 或 0 |
是 |
|
是 |
是 |
NULL |
U |
0 |
NULL |
|
是 |
是 |
NULL |
U |
1 或 0 |
NULL |
|
是 |
NULL |
NULL |
C |
0 |
NULL |
|
是 |
NULL |
NULL |
C |
1 或 0 |
NULL |
复杂数组¶
NumPy 风格:形状和步长¶
NumPy 风格数组的逻辑结构由 itemsize
、ndim
、shape
和 strides
定义。
如果 ndim == 0
,则由 buf
指向的内存位置被解释为大小为 itemsize
的标量。在这种情况下,shape
和 strides
都为 NULL
。
如果 strides
为 NULL
,则该数组被解释为标准的 n 维 C 数组。否则,使用者必须按如下方式访问 n 维数组
ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);
如上所述,buf
可以指向实际内存块中的任何位置。导出器可以使用此函数检查缓冲区的有效性
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
"""Verify that the parameters represent a valid array within
the bounds of the allocated memory:
char *mem: start of the physical memory block
memlen: length of the physical memory block
offset: (char *)buf - mem
"""
if offset % itemsize:
return False
if offset < 0 or offset+itemsize > memlen:
return False
if any(v % itemsize for v in strides):
return False
if ndim <= 0:
return ndim == 0 and not shape and not strides
if 0 in shape:
return True
imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] <= 0)
imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] > 0)
return 0 <= offset+imin and offset+imax+itemsize <= memlen
PIL 风格:shape、strides 和 suboffsets¶
除了常规项之外,PIL 风格的数组还可以包含必须跟踪的指针,以便获取维度中的下一个元素。例如,常规的三维 C 数组 char v[2][2][3]
也可以被视为指向两个二维数组的 2 个指针的数组:char (*v[2])[2][3]
。在 suboffsets 表示中,这两个指针可以嵌入在 buf
的开头,指向两个 char x[2][3]
数组,它们可以位于内存中的任何位置。
以下是一个函数,当存在非 NULL
strides 和 suboffsets 时,返回指向 N 维数组中由 N 维索引指向的元素的指针
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}