10.7 バッファオブジェクト構造体 (buffer object structure)

バッファインタフェースは、あるオブジェクトの内部データを一連のデータチャンク (chunk) として見せるモデルを外部から利用できるようにします。各チャンクはポインタ/データ長からなるペアで指定します。チャンクはセグメント(segment) と呼ばれ、メモリ内に不連続的に配置されるものと想定されています。

バッファインタフェースを利用できるようにしたくないオブジェクトでは、PyTypeObject 構造体の tp_as_buffer メンバを NULLにしなくてはなりません。利用できるようにする場合、 tp_as_buffer はPyBufferProcs 構造体を指さねばなりません。

注意: PyTypeObject 構造体の tp_flags メンバの値を 0 でなく Py_TPFLAGS_DEFAULT にしておくことがとても重要です。この設定は、 PyBufferProcs 構造体に bf_getcharbuffer スロットが入っていることを Python ランタイムに教えます。 Python の古いバージョンには bf_getcharbuffer メンバが存在しないので、古い拡張モジュールを使おうとしている新しいバージョンの Python インタプリタは、このメンバがあるかどうかテストしてから使えるようにする必要があるのです。

PyBufferProcs

バッファプロトコルの実装を定義している関数群へのポインタを保持するのに使われる構造体です。

最初のスロットはbf_getreadbuffer で、 getreadbufferproc 型です。このスロットが NULLの場合、オブジェクトは内部データの読み出しをサポートしません。そのような仕様には意味がないので、実装を行う側はこのスロットに値を埋めるはずですが、呼び出し側では非 NULL の値かどうかきちんと調べておくべきです。

次のスロットは bf_getwritebuffer で、 getwritebufferproc 型です。オブジェクトが返すバッファに対して書き込みを許可しない場合はこのスロットをNULL にできます。

第三のスロットは bf_getsegcount で、 getsegcountproc 型です。このスロットは NULL であってはならず、オブジェクトにいくつセグメントが入っているかを呼び出し側に教えるために使われます。PyString_Type や PyBuffer_Type オブジェクトのような単純なオブジェクトには単一のセグメントしか入っていません。

最後のスロットは bf_getcharbuffer で、 getcharbufferproc です。オブジェクトの PyTypeObject 構造体における tp_flags フィールドに、 Py_TPFLAGS_HAVE_GETCHARBUFFER ビットフラグがセットされている場合にのみ、このスロットが存在することになります。このスロットの使用に先立って、呼び出し側は PyType_HasFeature() を使ってスロットが存在するか調べねばなりません。フラグが立っていても、bf_getcharbufferは NULLのときもあり、 NULLはオブジェクトの内容を 8 ビット文字列 として利用できないことを示します。このスロットに入る関数も、オブジェクトの内容を 8 ビット文字列に変換できない場合に例外を送出することがあります。例えば、オブジェクトが浮動小数点数を保持するように設定されたアレイの場合、呼び出し側が bf_getcharbuffer を使って 8 ビット文字列としてデータを取り出そうとすると例外を送出するようにできます。この、内部バッファを ``テキスト'' として取り出すという概念は、本質的にはバイナリで、文字ベースの内容を持ったオブジェクト間の区別に使われます。

注意: 現在のポリシでは、文字 (character) はマルチバイト文字でもかまわないと決めているように思われます。従って、サイズ N のバッファが N 個のキャラクタからなるとはかぎらないことになります。

Py_TPFLAGS_HAVE_GETCHARBUFFER: 型構造体中のフラグビットで、bf_getcharbuffer スロットが既知の値になっていることを示します。このフラグビットがセットされていたとしても、オブジェクトがバッファインタフェースをサポートしていることや、bf_getcharbuffer スロットが NULLでないことを示すわけではありません。

Py_ssize_t (*getreadbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr): *ptrptrの中の読み出し可能なバッファセグメントへのポインタを返します。この関数は例外を送出してもよく、送出する場合には -1 を返さねばなりません。 segment に渡す値はゼロまたは正の値で、bf_getsegcount スロット関数が返すセグメント数よりも必ず小さな値でなければなりません。成功すると、セグメントのサイズを返し、 *ptrptr をそのセグメントを指すポインタ値にセットします。

Py_ssize_t (*getwritebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr): 読み出し可能なバッファセグメントへのポインタを *ptrptr に返し、セグメントの長さを関数の戻り値として返します。エラーによる例外の場合には -1 を-1 を返さねばなりません。オブジェクトが呼び出し専用バッファしかサポートしていない場合には TypeError を、segment が存在しないセグメントを指している場合には SystemError を送出しなければなりません。

Py_ssize_t (*getsegcountproc) (PyObject *self, Py_ssize_t *lenp): バッファを構成するメモリセグメントの数を返します。 lenp が NULLでない場合、この関数の実装は全てのセグメントのサイズ (バイト単位) の合計値を *lenp を介して報告しなければなりません。この関数呼び出しは失敗させられません。

Py_ssize_t (*getcharbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr): セグメント segment のメモリバッファを ptrptr に入れ、そのサイズを返します。エラーのときに -1 を返します。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。