缓冲结构

缓冲结构（或简称“缓冲区”）可用作将二进制数据从另一个对象暴露给Python程序员。它们也可以用作零拷贝切片机制。利用它们引用内存的能力，可以轻松地将任何数据公开给Python程序员。内存可以是C扩展中的大型常量数组，它可以是在传递给操作系统库之前进行操作的原始内存块，也可以用于将结构化数据传递给其本机内存格式.

与Python解释器公开的大多数数据类型相反，缓冲区不是PyObject指针，而不是简单的C结构。这允许非常简单地创建和复制它们。当需要通用包装缓冲区时，memoryview 对象可以创建.

关于如何编写导出对象的简短说明，请参阅缓冲区对象结构。要获得缓冲区，请参阅PyObject_GetBuffer().

Py_buffer

void * buf

指向缓冲区所描述的逻辑结构的开始的指针。这可以是导出器的基础物理内存块中的任何位置。例如，负面strides该值可能指向内存块的末尾.

对于连续的数组，该值指向内存块的开头.

void * obj

对导出对象的新引用。引用由消费者拥有并自动递减并设置为NULL PyBuffer_Release()。该字段相当于任何标准C-API函数的返回值.

作为一个特例，对于temporary由包裹的缓冲区PyMemoryView_FromBuffer()要么 PyBuffer_FillInfo()这个字段是NULL。一般情况下，导出对象不得使用此方案.

Py_ssize_t len

product(shape) * itemsize。对于连续数组，这是底层内存块的长度。对于非连续数组，它是逻辑结构复制到连续表示时的长度.

访问((char *)buf)[0] up to ((char *)buf)[len-1]只有在保证连续性的请求获得缓冲区时才有效。在大多数情况下，这样的请求将是PyBUF_SIMPLE或PyBUF_WRITABLE.

int readonly

指示缓冲区是否为只读。该字段由PyBUF_WRITABLE flag.

Py_ssize_t itemsize

单个元素的项目大小（以字节为单位）控制。与非// struct.calcsize()上调用的值相同format values.

重要异常：如果消费者请求没有PyBUF_FORMAT标志的缓冲区，format将设置为NULL，但itemsize仍然具有原始格式的值.

如果shape存在，则相等product(shape) * itemsize == len仍然持有，消费者可以使用itemsize导航缓冲区

如果shape是NULL由于PyBUF_SIMPLE或PyBUF_WRITABLE请求，消费者必须忽视itemsize并假设itemsize == 1.

const char * format

A NUL在struct模块样式语法中终止字符串，描述单个项目的内容。如果这是NULL, "B"（无符号字节）假设

这个字段是由PyBUF_FORMAT flag.

int ndim

控制的内存表示为n维数组的维数。如果0, buf指向表示标量的单个项目。在这种情况下，shape, strides和suboffsets必须是NULL.

宏PyBUF_MAX_NDIM限制维度的最大数量64.出口商必须尊重这个限制，多个消费者-dimensionalbuffers应该能够处理最大PyBUF_MAX_NDIM dimensions.

Py_ssize_t * shape

Py_ssize_t长度为ndim的数组表示作为n维数组的存储器的形状。注意shape[0] * ... * shape[ndim-1] * itemsize必须等于len.

形状值限制为shape[n] >= 0。案件shape[n] == 0需要特别注意。有关详细信息，请参阅复杂阵列.

形状数组对于消费者来说是只读的.

Py_ssize_t * strides

Py_ssize_t长度ndim的数组给出要跳过的字节数在eachdimension中获取一个新元素.

两个值可以是任何整数。对于常规阵列，步幅通常是正面的，但消费者必须能够处理strides[n] <= 0的情况。有关详细信息，请参见复杂数组.

strides数组对于消费者来说是只读的.

Py_ssize_t * suboffsets

数组Py_ssize_t的长度ndim。如果suboffsets[n] >= 0，沿第n维存储的值是指针，子偏移值指示在取消引用后要添加到每个指针的字节数。一个负偏移的子偏移值表示不应该发生解引用（跨越连续内存块）.

如果所有子偏移都是负数（即不需要解引用），则该字段必须为NULL（默认值）值）。

Python成像库（PIL）使用这种类型的数组表示。有关如何访问此类数组的元素的更多信息，请参阅复杂数组.

suboffsets数组对于使用者是只读的.

void * internal

这是内部使用由出口对象。例如，导出器可能会将此值重新转换为整数，并用于存储标记，以确定缓冲区释放时是否必须同步形状，跨步和子偏移数组。消费者不得改变这个值

缓冲请求类型

缓冲区通常是通过PyObject_GetBuffer()向exportobject发送缓冲请求来获得的。由于内存的逻辑结构的复杂性可能会有很大的不同，消费者使用flags参数来指定它可以处理的确切缓冲区类型.

所有Py_buffer字段都是明确的由requesttype.

复杂数组

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

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;
}

与缓冲区相关的函数

int PyObject_CheckBuffer（ PyObject  *obj）

返回1如果obj支持缓冲区接口，否则0。当1回复时，不能保证PyObject_GetBuffer()将会成功。这个功能总是成功的.

int PyObject_GetBuffer（ PyObject  *exporter，Py_buffer  *view，int  flags）

根据exporter的规定向view发送填写flags。如果出口商无法提供确切类型的缓冲区，则必须提高PyExc_BufferError，设置view->obj至NULL并返回-1.

成功时，填写view，将view->obj设为exporter在链接缓冲区的情况下，将请求重定向到单个对象，view->obj MAYrefer to this object而不是exporter（参见缓冲区对象结构).

成功调用PyObject_GetBuffer()必须与callsto PyBuffer_Release()配对，类似于malloc()和free()。因此，在消费者完成缓冲后，PyBuffer_Release()必须恰好叫一次.

void PyBuffer_Release（Py_buffer  *view）

释放缓冲区view并减去view->obj的引用计数。当缓冲区不再使用时必须调用此函数，否则可能会发生引用泄漏.

在没有通过PyObject_GetBuffer().

Py_ssize_t PyBuffer_SizeFromFormat（const char  *）

返回隐含的itemsize来自format。这个功能还没有实现.

int PyBuffer_IsContiguous（ Py_buffer  *view，char  order）

如果1定义的内存是C风格（view是order）或Fortran风格（"C"，则返回order是"F"）连续或其中任何一个（order是"A"）。否则返回0。这个功能总是成功的.

int PyBuffer_ToContiguous（ void  *buf，Py_buffer  *src，Py_ssize_t  len，char order）

从len复制src字节到buf.order中的连续表示可以是"C"或"F"（对于C风格或Fortran风格的订购）.0成功退货，-1出错.

如果len！= src->len.

void PyBuffer_FillContiguousStrides（ int  ndims，Py_ssize_t  *shape，Py_ssize_t  *strides,int  itemsize，char  order）

用strides连续的字节跨度填充数组（C风格如果order是"C"或Fortran风格，如果order是"F"）给定形状的数组，每个元素有给定的字节数。

int PyBuffer_FillInfo（ Py_buffer  *view，PyObject  *exporter，void  *buf，Py_ssize_t  len，int  readonly，int  flags）

处理想要公开的导出器的缓冲请求buf大小len根据readonly. buf被解释为无符号字节的序列.

flags参数表示请求类型。除非view，否则此函数总是按标志指定的buf已被指定为只读和PyBUF_WRITABLE设置在flags.

成功时，将view->obj设置为对exporter的新引用并返回0.否则，引发PyExc_BufferError，设置view->obj到NULL并返回-1;

如果此函数用作 getbufferproc的一部分,exporter必须设置为导出对象，并且必须传递flags。否则，exporter必须是NULL.