緩沖區結構?

緩沖區結構(或者簡(jiǎn)單地稱(chēng)為“buffers”)對于將二進(jìn)制數據從另一個(gè)對象公開(kāi)給 Python 程序員非常有用。它們還可以用作零拷貝切片機制。使用它們引用內存塊的能力，可以很容易地將任何數據公開(kāi)給 Python 程序員。內存可以是 C 擴展中的一個(gè)大的常量數組，也可以是在傳遞到操作系統庫之前用于操作的原始內存塊，或者可以用來(lái)傳遞本機內存格式的結構化數據。

與 Python 解釋器公開(kāi)的大多部數據類(lèi)型不同，緩沖區不是 PyObject 指針而是簡(jiǎn)單的 C 結構。 這使得它們可以非常簡(jiǎn)單地創(chuàng )建和復制。 當需要為緩沖區加上泛型包裝器時(shí)，可以創(chuàng )建一個(gè) 內存視圖 對象。

有關(guān)如何編寫(xiě)并導出對象的簡(jiǎn)短說(shuō)明，請參閱 緩沖區對象結構。 要獲取緩沖區對象，請參閱 PyObject_GetBuffer()。

type Py_buffer?

Part of the Stable ABI (including all members) since version 3.11.

void *buf?

指向由緩沖區字段描述的邏輯結構開(kāi)始的指針。 這可以是導出程序底層物理內存塊中的任何位置。 例如，使用負的 strides 值可能指向內存塊的末尾。

對于 contiguous ，‘鄰接’數組，值指向內存塊的開(kāi)頭。

void *obj?

對導出對象的新引用。 該引用歸使用者所有，并由 PyBuffer_Release() 自動(dòng)遞減并設置為 NULL。 該字段等于任何標準 C-API 函數的返回值。

作為一種特殊情況，對于由 PyMemoryView_FromBuffer() 或 PyBuffer_FillInfo() 包裝的 temporary 緩沖區，此字段為 NULL。 通常，導出對象不得使用此方案。

Py_ssize_t len?

product(shape) * itemsize。對于連續數組，這是基礎內存塊的長(cháng)度。對于非連續數組，如果邏輯結構復制到連續表示形式，則該長(cháng)度將具有該長(cháng)度。

僅當緩沖區是通過(guò)保證連續性的請求獲取時(shí)，才訪(fǎng)問(wèn) ((char *)buf)[0] up to ((char *)buf)[len-1] 時(shí)才有效。在大多數情況下，此類(lèi)請求將為 PyBUF_SIMPLE 或 PyBUF_WRITABLE。

int readonly?

緩沖區是否為只讀的指示器。此字段由 PyBUF_WRITABLE 標志控制。

Py_ssize_t itemsize?

單個(gè)元素的項大?。ㄒ宰止潪閱挝唬?。與 struct.calcsize() 調用非 NULL format 的值相同。

重要例外：如果使用者請求的緩沖區沒(méi)有 PyBUF_FORMAT 標志，format 將設置為 NULL，但 itemsize 仍具有原始格式的值。

如果 shape 存在，則相等的 product(shape) * itemsize == len 仍然存在，使用者可以使用 itemsize 來(lái)導航緩沖區。

如果 shape 是 NULL，因為結果為 PyBUF_SIMPLE 或 PyBUF_WRITABLE 請求，則使用者必須忽略 itemsize，并假設 itemsize == 1。

const char *format?

在 struct 模塊樣式語(yǔ)法中 NUL 字符串，描述單個(gè)項的內容。如果這是 NULL，則假定為``"B"`` (無(wú)符號字節) 。

此字段由 PyBUF_FORMAT 標志控制。

int ndim?

內存表示為 n 維數組的維數。 如果是``0``， buf 指向表示標量的單個(gè)項目。 在這種情況下，shape、strides 和 suboffsets 必須是``NULL`` 。

宏 PyBUF_MAX_NDIM 將最大維度數限制為 64。 導出程序必須遵守這個(gè)限制，多維緩沖區的使用者應該能夠處理最多 PyBUF_MAX_NDIM 維度。

Py_ssize_t *shape?

一個(gè)長(cháng)度為 Py_ssize_t 的數組 ndim 表示作為 n 維數組的內存形狀。 請注意，shape[0] * ... * shape[ndim-1] * itemsize 必須等于 len。

Shape 形狀數組中的值被限定在 shape[n] >= 0 。 shape[n] == 0 這一情形需要特別注意。更多信息請參閱 complex arrays 。

shape 數組對于使用者來(lái)說(shuō)是只讀的。

Py_ssize_t *strides?

一個(gè)長(cháng)度為 Py_ssize_t 的數組 ndim 給出要跳過(guò)的字節數以獲取每個(gè)尺寸中的新元素。

Stride 步幅數組中的值可以為任何整數。對于常規數組，步幅通常為正數，但是使用者必須能夠處理 strides[n] <= 0 的情況。更多信息請參閱 complex arrays 。

strides數組對用戶(hù)來(lái)說(shuō)是只讀的。

Py_ssize_t *suboffsets?

一個(gè)長(cháng)度為 ndim 類(lèi)型為 Py_ssize_t 的數組 。如果 suboffsets[n] >= 0，則第 n 維存儲的是指針，suboffset 值決定了解除引用時(shí)要給指針增加多少字節的偏移。suboffset 為負值，則表示不應解除引用（在連續內存塊中移動(dòng)）。

如果所有子偏移均為負（即無(wú)需取消引用），則此字段必須為 NULL （默認值）。

Python Imaging Library (PIL) 中使用了這種類(lèi)型的數組表達方式。請參閱 complex arrays 來(lái)了解如何從這樣一個(gè)數組中訪(fǎng)問(wèn)元素。

suboffsets 數組對于使用者來(lái)說(shuō)是只讀的。

void *internal?

供輸出對象內部使用。比如可能被輸出程序重組為一個(gè)整數，用于存儲一個(gè)標志，標明在緩沖區釋放時(shí)是否必須釋放 shape、strides 和 suboffsets 數組。消費者程序 不得 修改該值。

緩沖區請求的類(lèi)型?

通常，通過(guò) PyObject_GetBuffer() 向輸出對象發(fā)送緩沖區請求，即可獲得緩沖區。由于內存的邏輯結構復雜，可能會(huì )有很大差異，緩沖區使用者可用 flags 參數指定其能夠處理的緩沖區具體類(lèi)型。

所有 Py_buffer 字段均由請求類(lèi)型明確定義。

復雜數組?

ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);

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

緩沖區相關(guān)函數?

int PyObject_CheckBuffer(PyObject *obj)?

Part of the Stable ABI since version 3.11.

如果 obj 支持緩沖區接口，則返回 1，否則返回 0。 返回 1 時(shí)不保證 PyObject_GetBuffer() 一定成功。本函數一定調用成功。

int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)?

Part of the Stable ABI since version 3.11.

向 輸出器程序 發(fā)送請求，按照 flags 指定的內容填充 view。如果 輸出器程序不能提供準確類(lèi)型的緩沖區，必須 觸發(fā) PyExc_BufferError，設置 view->obj 為 NULL 并返回 -1。

成功時(shí)，填充 view，將 view->obj 設為對 exporter 的新引用，并返回 0。 當鏈式緩沖區提供程序將請求重定向到一個(gè)對象時(shí)，view->obj 可以引用該對象而不是 exporter (參見(jiàn) 緩沖區對象結構)。

PyObject_GetBuffer() 必須與 PyBuffer_Release() 同時(shí)調用成功，類(lèi)似于 malloc() 和 free()。因此，消費者程序用完緩沖區后， PyBuffer_Release() 必須保證被調用一次。

void PyBuffer_Release(Py_buffer *view)?

Part of the Stable ABI since version 3.11.

釋放緩沖區 view 并遞減 view->obj 的引用計數。該函數必須在緩沖區不再使用時(shí)才能調用，否則可能會(huì )發(fā)生引用泄漏。

若該函數針對的緩沖區不是通過(guò) PyObject_GetBuffer() 獲得的，將會(huì )出錯。

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)?

Part of the Stable ABI since version 3.11.

返回 itemsize 中隱含的 format 。如果出錯，會(huì )觸發(fā)異常并返回 -1。

3.9 新版功能.

int PyBuffer_IsContiguous(const Py_buffer *view, char order)?

Part of the Stable ABI since version 3.11.

如果 view 定義的內存是 C 風(fēng)格（order 為 'C'）或 Fortran 風(fēng)格（order 為 'F'） contiguous 或其中之一（order 是 'A'），則返回 1。否則返回 0。該函數總會(huì )成功。

void *PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)?

Part of the Stable ABI since version 3.11.

獲取給定 view 內的 indices 所指向的內存區域。indices 必須指向一個(gè) view->ndim 索引的數組。

int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)?

Part of the Stable ABI since version 3.11.

從 buf 復制連續的 len 字節到 view 。fort 可以是 'C' 或 'F'``（對應于 C 風(fēng)格或 Fortran 風(fēng)格的順序）。成功時(shí)返回  ``0，錯誤時(shí)返回 -1。

int PyBuffer_ToContiguous(void *buf, const Py_buffer *src, Py_ssize_t len, char order)?

Part of the Stable ABI since version 3.11.

從 src 復制 len 字節到 buf ，成為連續字節串的形式。order 可以是 'C' 或 'F' 或 'A'``（對應于 C 風(fēng)格、Fortran 風(fēng)格的順序或其中任意一種）。成功時(shí)返回 ``0，出錯時(shí)返回 -1。

如果 len != src->len 則此函數將報錯。

int PyObject_CopyData(Py_buffer *dest, Py_buffer *src)?

Part of the Stable ABI since version 3.11.

Copy data from src to dest buffer. Can convert between C-style and or Fortran-style buffers.

0 is returned on success, -1 on error.

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)?

Part of the Stable ABI since version 3.11.

用給定形狀的 contiguous 字節串數組 (如果 order 為 'C' 則為 C 風(fēng)格，如果 order 為 'F' 則為 Fortran 風(fēng)格) 來(lái)填充 strides 數組，每個(gè)元素具有給定的字節數。

int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)?

Part of the Stable ABI since version 3.11.

處理導出程序的緩沖區請求，該導出程序要公開(kāi)大小為 len 的 buf ，并根據 readonly 設置可寫(xiě)性。bug 被解釋為一個(gè)無(wú)符號字節序列。

參數 flags 表示請求的類(lèi)型。該函數總是按照 flag 指定的內容填入 view，除非 buf 設為只讀，并且 flag 中設置了 PyBUF_WRITABLE 標志。

成功時(shí)，將 view->obj 設為 exporter 的新引用，并返回 0。否則，引發(fā) PyExc_BufferError ，將 view->obj 設為 NULL，并返回 -1。

如果此函數用作 getbufferproc 的一部分，則 exporter 必須設置為導出對象，并且必須在未修改的情況下傳遞 flags。否則，exporter 必須是 NULL。