缓冲区相关函数

xhz

int PyObject_CheckBuffer(PyObject *obj)
属于 稳定 ABI 自 3.11 版开始.
如果 obj 支持缓冲区接口，则返回 1，否则返回 0。 返回 1 时不保证 PyObject_GetBuffer() 一定成功。本函数一定调用成功。

int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
属于 稳定 ABI 自 3.11 版开始.
向 exporter 发送请求以按照 flags 指定的内容填充 view。 如果 exporter 无法提供要求类型的缓冲区，则它必须引发 BufferError，将 view->obj 设为 NULL 并返回 -1。

成功时，填充 view，将 view->obj 设为对 exporter 的新引用，并返回 0。 当链式缓冲区提供程序将请求重定向到一个对象时，view->obj 可以引用该对象而不是 exporter (参见 缓冲区对象结构)。

PyObject_GetBuffer() 必须与 PyBuffer_Release() 同时调用成功，类似于 malloc() 和 free()。因此，消费者程序用完缓冲区后， PyBuffer_Release() 必须保证被调用一次。

void PyBuffer_Release(Py_buffer *view)
属于 稳定 ABI 自 3.11 版开始.
释放缓冲区 view 并释放对视图的支持对象 view->obj 的 strong reference (即递减引用计数)。 该函数必须在缓冲区不再使用时调用，否则可能会发生引用泄漏。

若该函数针对的缓冲区不是通过 PyObject_GetBuffer() 获得的，将会出错。

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
属于 稳定 ABI 自 3.11 版开始.
从 format 返回隐含的 itemsize。 如果出错，则引发异常并返回 -1。

在 3.9 版本加入.

int PyBuffer_IsContiguous(const Py_buffer *view, char order)
属于 稳定 ABI 自 3.11 版开始.
如果 view 定义的内存是 C 风格（order 为 'C'）或 Fortran 风格（order 为 'F'） contiguous 或其中之一（order 是 'A'），则返回 1。否则返回 0。该函数总会成功。

void *PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)
属于 稳定 ABI 自 3.11 版开始.
获取给定 view 内的 indices 所指向的内存区域。indices 必须指向一个 view->ndim 索引的数组。

int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)
属于 稳定 ABI 自 3.11 版开始.
从 buf 复制连续的 len 字节到 view 。fort 可以是 'C' 或 'F' （对应于 C 风格或 Fortran 风格的顺序）。成功时返回 0 ，错误时返回 -1 。

int PyBuffer_ToContiguous(void *buf, const Py_buffer *src, Py_ssize_t len, char order)
属于 稳定 ABI 自 3.11 版开始.
从 src 复制 len 字节到 buf ，成为连续字节串的形式。order 可以是 'C' 或 'F' 或 'A' （对应于 C 风格、Fortran 风格的顺序或其中任意一种）。成功时返回 0 ，出错时返回 -1 。

如果 len != src->len 则此函数将报错。

int PyObject_CopyData(PyObject *dest, PyObject *src)
属于 稳定 ABI 自 3.11 版开始.
将数据从 src 拷贝到 dest 缓冲区。 可以在 C 风格或 Fortran 风格的缓冲区之间进行转换。

成功时返回 0，出错时返回 -1。

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
属于 稳定 ABI 自 3.11 版开始.
用给定形状的 contiguous 字节串数组 (如果 order 为 'C' 则为 C 风格，如果 order 为 'F' 则为 Fortran 风格) 来填充 strides 数组，每个元素具有给定的字节数。

int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
属于 稳定 ABI 自 3.11 版开始.
处理导出程序的缓冲区请求，该导出程序要公开大小为 len 的 buf ，并根据 readonly 设置可写性。bug 被解释为一个无符号字节序列。

参数 flags 表示请求的类型。该函数总是按照 flag 指定的内容填入 view，除非 buf 设为只读，并且 flag 中设置了 PyBUF_WRITABLE 标志。

成功时，将 view->obj 设为对 exporter 的新引用并返回 0。 否则，引发 BufferError，将 view->obj 设为 NULL 并返回 -1；

如果此函数用作 getbufferproc 的一部分，则 exporter 必须设置为导出对象，并且必须在未修改的情况下传递 flags。否则，exporter 必须是 NULL。