buffer 構造体¶

バッファ構造体（または単純に "buffers"）は別のオブジェクトのバイナリデータをPythonプログラマに提供するのに便利です。これはまた、ゼロコピースライシング機構としても使用できます。このメモリブロックを参照する機能を使うことで、どんなデータでもとても簡単にPythonプログラマに提供することができます。メモリは、C 拡張の大きな配列定数かもしれませんし、オペレーティングシステムライブラリに渡す前のメモリブロックかもしれませんし、構造化データをネイティブのインメモリ形式受け渡すのに使用されるかもしれません。

Pythonインタプリタによって提供される多くのデータ型とは異なり、バッファは PyObject ポインタではなく、シンプルなC 構造体です。そのため、作成とコピーが非常に簡単に行えます。バッファの一般的なラッパーが必要なときは、 memoryview オブジェクトが作成されます。

エクスポートされるオブジェクトを書く方法の短い説明には、 Buffer Object Structures を参照してください。バッファを取得するには、 PyObject_GetBuffer() を参照してください。

type Py_buffer¶

次に属します: Stable ABI (すべてのメンバーを含む) (バージョン 3.11 より).

void *buf¶

バッファフィールドが表している論理構造の先頭を指すポインタ。 バッファを提供するオブジェクトの下層物理メモリブロック中のどの位置にもなりえます。 例えば strides が負だと、この値はメモリブロックの末尾かもしれません。

連続 配列の場合この値はメモリブロックの先頭を指します。

PyObject *obj¶

バッファを提供するオブジェクトへの新しい参照です。 この参照は利用側が所有し、PyBuffer_Release() によって自動的に解放 (参照カウントを減少) され、NULL に設定されます。 このフィールドは、通常の C API 関数の戻り値に相当します。

PyMemoryView_FromBuffer() または PyBuffer_FillInfo() によってラップされた 一時的な バッファである特別なケースでは、このフィールドは NULL です。一般的に、エクスポートオブジェクトはこの方式を使用してはなりません。

Py_ssize_t len¶

product(shape) * itemsize。contiguous配列では、下層のメモリブロックの長さになります。非contiguous 配列では、contiguous表現にコピーされた場合に論理構造がもつ長さです。

((char *)buf)[0] から ((char *)buf)[len-1] の範囲へのアクセスは、連続性 (contiguity) を保証するリクエストによって取得されたバッファに対してのみ許されます。 多くの場合に、そのようなリクエストは PyBUF_SIMPLE または PyBUF_WRITABLE です。

int readonly¶

バッファが読み出し専用であるか示します。このフィールドは PyBUF_WRITABLE フラグで制御できます。

Py_ssize_t itemsize¶

要素一つ分のbyte単位のサイズ。 struct.calcsize() を非 NULL の format 値に対して呼び出した結果と同じです。

重要な例外: 利用側が PyBUF_FORMAT フラグなしでバッファを要求した場合、format は NULL に設定されますが、itemsize は元の形式に対応する値を保持します。

shape が存在する場合、 product(shape) * itemsize == len の等式が守られ、利用者は itemsize を buffer を読むために利用できます。

PyBUF_SIMPLE または PyBUF_WRITABLE で要求した結果、 shape が NULL であれば、消費者は itemsize を無視して itemsize == 1 と見なさなければなりません。

char *format¶

単一の要素の内容を struct モジュール形式の構文で記述した、ヌル終端文字列です。 NULL の場合は "B" (符号なしバイト) とみなします。

このフィールドは PyBUF_FORMAT フラグによって制御されます。

int ndim¶

メモリを n 次元配列として表すときの次元数です。 0 の場合、buf はスカラを表す単一の要素を指します。 この場合、shape、strides、suboffsets は NULL でなければなりません。 次元数の上限は PyBUF_MAX_NDIM で定義されています。

Py_ssize_t *shape¶

メモリ上のN次元配列の形を示す、長さが ndim である Py_ssize_t の配列です。 shape[0] * ... * shape[ndim-1] * itemsize は len と等しくなければなりません。

shape の値は shape[n] >= 0 に制限されます。 shape[n] == 0 の場合に特に注意が必要です。 詳細は complex arrays を参照してください。

shape 配列は利用側にとって読み取り専用です。

Py_ssize_t *strides¶

各次元において新しい値を得るためにスキップするバイト数を示す、長さ ndim の Py_ssize_t の配列。

ストライドの値は任意の整数です。 通常の配列ではストライドは一般に正ですが、利用側は strides[n] <= 0 の場合も扱えなければなりません。 詳細は complex arrays を参照してください。

消費者にとって、この strides 配列は読み出し専用です。

Py_ssize_t *suboffsets¶

Py_ssize_t 型の要素を持つ長さ ndim の配列。 suboffsets[n] >= 0 の場合は、 n 番目の次元に沿って保存されている値はポインタで、 suboffset 値は各ポインタの参照を解決した後に何バイト加えればいいかを示しています。 suboffset の値が負の数の場合は、ポインタの参照解決は不要 (連続したメモリブロック内に直接配置されいる) ということになります。

全ての suboffset が負数の場合 (つまり参照解決が不要) な場合、このフィールドは NULL (デフォルト値) でなければなりません。

この種の配列表現は Python Imaging Library (PIL) で使われています。 このような配列で要素にアクセスする方法についてさらに詳しことは complex arrays を参照してください。

消費者にとって、suboffsets 配列は読み出し専用です。

void *internal¶

バッファを提供する側のオブジェクトが内部的に利用するための変数です。例えば、提供側はこの変数に整数型をキャストして、shape, strides, suboffsets といった配列をバッファを開放するときに同時に解放するべきかどうかを管理するフラグに使うことができるでしょう。バッファを受け取る側は、この値を決して変更してはなりません。

定数。

PyBUF_MAX_NDIM¶

次に属します: Stable ABI (バージョン 3.11 より).

メモリを表す次元数の上限です。 バッファの提供側はこの上限を守らなければなりません。 多次元バッファの利用側は PyBUF_MAX_NDIM 次元まで扱えるべきです。 現在は 64 に設定されています。

バッファリクエストのタイプ¶

バッファは通常、 PyObject_GetBuffer() を使うことで、エクスポートするオブジェクトにバッファリクエストを送ることで得られます。メモリの論理的な構造の複雑性は多岐にわたるため、消費者は flags 引数を使って、自身が扱えるバッファの種類を指定します。

Py_buffer の全フィールドは、リクエストの種類によって曖昧さを残さずに定義されます。

複雑な配列¶

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):
    """引数が、割り当てたメモリの範囲内の有効な配列を
       表しているかどうかを検証する:
           char *mem: 物理メモリブロックの先頭
           memlen: 物理メモリブロックの長さ
           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)¶

次に属します: Stable ABI (バージョン 3.11 より).

obj がbuffer インターフェースをサポートしている場合は 1 を返し、そうでない場合は 0 を返します。 1 を返したとしても、 PyObject_GetBuffer() が成功することは保証されません。 この関数は常に成功します。

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

次に属します: Stable ABI (バージョン 3.11 より).

exporter に flags で指定された方法で view を埋めるように要求します。もし exporter が指定されたとおりにバッファを提供できない場合、 BufferError を送出し、 view->obj を NULL に設定した上で、 -1 を返さなければなりません。

成功した場合は view に情報を設定し、view->obj を exporter への新しい参照にして 0 を返します。 複数のバッファ提供側が連鎖し、要求を一つのオブジェクトに転送する場合は、view->obj が exporter の代わりにそのオブジェクトを参照しても構いません (バッファオブジェクト構造体 を参照)。

malloc() と free() のように、呼び出しに成功した PyObject_GetBuffer() と対になる PyBuffer_Release() の呼び出しがなけれなればなりません。 従って、バッファの利用が済んだら PyBuffer_Release() が厳密に1回だけ呼び出されなければなりません。

void PyBuffer_Release(Py_buffer *view)¶

次に属します: Stable ABI (バージョン 3.11 より).

バッファ view を解放し、ビューを支えるオブジェクト view->obj への 強参照 も解放します (つまり参照カウントを減らします)。 バッファを使わなくなったときは必ず呼び出してください。 呼び出さないと参照がリークする可能性があります。

PyObject_GetBuffer() を通して取得していないバッファに対してこの関数を呼び出すのは間違いです。

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)¶

次に属します: Stable ABI (バージョン 3.11 より).

format が表す itemsize を返します。 エラーの場合は例外を送出し、-1 を返します。

Added in version 3.9.

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

次に属します: Stable ABI (バージョン 3.11 より).

view で定義されているメモリが、 C スタイル (order == 'C') のときか、 Fortran スタイル (order == 'F') 連続 のときか、そのいずれか (order == 'A') であれば 1 を返します。 それ以外の場合は 0 を返します。 この関数は常に成功します。

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

次に属します: Stable ABI (バージョン 3.11 より).

与えられた view 内にある indices が指すメモリ領域を取得します。 indices は view->ndim 個のインデックスからなる配列を指していなければなりません。

int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char order)¶

次に属します: Stable ABI (バージョン 3.11 より).

buf の連続した len バイトを view にコピーします。 order は 'C'、'F'、'A' のいずれかで、それぞれ C スタイル、Fortran スタイル、どちらでもよいことを表します。 成功した場合は 0 を返し、エラーの場合は -1 を返します。

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

次に属します: Stable ABI (バージョン 3.11 より).

src の len バイトを、buf 内の連続した表現にコピーします。 order は 'C'、'F'、'A' のいずれかで、それぞれ C スタイル、Fortran スタイル、どちらでもよいことを表します。 成功した場合は 0 を返し、エラーの場合は -1 を返します。

len != src->len の場合、この関数は失敗します。

int PyObject_CopyData(PyObject *dest, PyObject *src)¶

次に属します: Stable 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)¶

次に属します: Stable ABI (バージョン 3.11 より).

指定された形状と要素あたりのバイト数を持つ 連続した 配列の、バイト単位のストライドを strides 配列に設定します。 order が 'C' なら C スタイル、'F' なら Fortran スタイルです。

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

次に属します: Stable ABI (バージョン 3.11 より).

サイズが len の buf を readonly に従った書き込み可/不可の設定で公開するバッファリクエストを処理します。 buf は符号無しバイトの列として解釈されます。

flags 引数は要求の種類を示します。 buf が読み取り専用なのに flags に PyBUF_WRITABLE が設定されている場合を除き、この関数は常に flags の指定どおりに view に情報を設定します。

成功した場合は view->obj を exporter への新しい参照に設定し、0 を返します。 それ以外の場合は BufferError を送出し、view->obj を NULL に設定して -1 を返します。

この関数を getbufferproc の一部として使う場合には、 exporter はエクスポートするオブジェクトに設定しなければならず、さらに flags は変更せずに渡さなければなりません。 そうでない場合は、 exporter は NULL でなければなりません。