緩沖協(xié)議?

緩沖區(qū)結(jié)構(gòu)?

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

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

有關(guān)如何編寫并導(dǎo)出對象的簡短說明，請參閱 緩沖區(qū)對象結(jié)構(gòu)。 要獲取緩沖區(qū)對象，請參閱 PyObject_GetBuffer()。

type Py_buffer?

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

void *buf?

指向由緩沖區(qū)字段描述的邏輯結(jié)構(gòu)開始的指針。 這可以是導(dǎo)出程序底層物理內(nèi)存塊中的任何位置。 例如，使用負(fù)的 strides 值可能指向內(nèi)存塊的末尾。

對于 contiguous ，‘鄰接’數(shù)組，值指向內(nèi)存塊的開頭。

void *obj?

對導(dǎo)出對象的新引用。 該引用歸使用者所有，并由 PyBuffer_Release() 自動遞減并設(shè)置為 NULL。 該字段等于任何標(biāo)準(zhǔn) C-API 函數(shù)的返回值。

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

Py_ssize_t len?

product(shape) * itemsize。對于連續(xù)數(shù)組，這是基礎(chǔ)內(nèi)存塊的長度。對于非連續(xù)數(shù)組，如果邏輯結(jié)構(gòu)復(fù)制到連續(xù)表示形式，則該長度將具有該長度。

僅當(dāng)緩沖區(qū)是通過保證連續(xù)性的請求獲取時，才訪問 ((char *)buf)[0] up to ((char *)buf)[len-1] 時才有效。在大多數(shù)情況下，此類請求將為 PyBUF_SIMPLE 或 PyBUF_WRITABLE。

int readonly?

緩沖區(qū)是否為只讀的指示器。此字段由 PyBUF_WRITABLE 標(biāo)志控制。

Py_ssize_t itemsize?

單個元素的項大?。ㄒ宰止?jié)為單位）。與 struct.calcsize() 調(diào)用非 NULL format 的值相同。

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

如果 shape 存在，則相等的 product(shape) * itemsize == len 仍然存在，使用者可以使用 itemsize 來導(dǎo)航緩沖區(qū)。

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

const char *format?

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

此字段由 PyBUF_FORMAT 標(biāo)志控制。

int ndim?

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

宏 PyBUF_MAX_NDIM 將最大維度數(shù)限制為 64。 導(dǎo)出程序必須遵守這個限制，多維緩沖區(qū)的使用者應(yīng)該能夠處理最多 PyBUF_MAX_NDIM 維度。

Py_ssize_t *shape?

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

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

shape 數(shù)組對于使用者來說是只讀的。

Py_ssize_t *strides?

一個長度為 Py_ssize_t 的數(shù)組 ndim 給出要跳過的字節(jié)數(shù)以獲取每個尺寸中的新元素。

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

strides數(shù)組對用戶來說是只讀的。

Py_ssize_t *suboffsets?

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

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

Python Imaging Library (PIL) 中使用了這種類型的數(shù)組表達(dá)方式。請參閱 complex arrays 來了解如何從這樣一個數(shù)組中訪問元素。

suboffsets 數(shù)組對于使用者來說是只讀的。

void *internal?

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

緩沖區(qū)請求的類型?

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

所有 Py_buffer 字段均由請求類型明確定義。

復(fù)雜數(shù)組?

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

緩沖區(qū)相關(guān)函數(shù)?

int PyObject_CheckBuffer(PyObject *obj)?

Part of the Stable ABI since version 3.11.

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

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

Part of the Stable ABI since version 3.11.

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

成功時，填充 view，將 view->obj 設(shè)為對 exporter 的新引用，并返回 0。 當(dāng)鏈?zhǔn)骄彌_區(qū)提供程序?qū)⒄埱笾囟ㄏ虻揭粋€對象時，view->obj 可以引用該對象而不是 exporter (參見 緩沖區(qū)對象結(jié)構(gòu))。

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

void PyBuffer_Release(Py_buffer *view)?

Part of the Stable ABI since version 3.11.

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

若該函數(shù)針對的緩沖區(qū)不是通過 PyObject_GetBuffer() 獲得的，將會出錯。

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)?

Part of the Stable ABI since version 3.11.

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

3.9 新版功能.

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

Part of the Stable ABI since version 3.11.

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

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

Part of the Stable ABI since version 3.11.

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

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 復(fù)制連續(xù)的 len 字節(jié)到 view 。fort 可以是 'C' 或 'F'``（對應(yīng)于 C 風(fēng)格或 Fortran 風(fēng)格的順序）。成功時返回  ``0，錯誤時返回 -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 復(fù)制 len 字節(jié)到 buf ，成為連續(xù)字節(jié)串的形式。order 可以是 'C' 或 'F' 或 'A'``（對應(yīng)于 C 風(fēng)格、Fortran 風(fēng)格的順序或其中任意一種）。成功時返回 ``0，出錯時返回 -1。

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

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 字節(jié)串?dāng)?shù)組 (如果 order 為 'C' 則為 C 風(fēng)格，如果 order 為 'F' 則為 Fortran 風(fēng)格) 來填充 strides 數(shù)組，每個元素具有給定的字節(jié)數(shù)。

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.

處理導(dǎo)出程序的緩沖區(qū)請求，該導(dǎo)出程序要公開大小為 len 的 buf ，并根據(jù) readonly 設(shè)置可寫性。bug 被解釋為一個無符號字節(jié)序列。

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

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

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