カプセル¶
using-capsules 以下のオブジェクトを使う方法については 拡張モジュールに C API を提供する を参照してください。
バージョン 3.1 で追加.
-
PyCapsule¶ この
PyObjectのサブタイプは、任意の値を表し、C拡張モジュールから Pythonコードを経由して他のC言語のコードに任意の値を(void*ポインタの形で)渡す必要があるときに有用です。あるモジュール内で定義されているC言語関数のポインタを、他のモジュールに渡してそこから呼び出せるようにするためによく使われます。これにより、動的にロードされるモジュールの中の C API に通常の import 機構を通してアクセスすることができます。
-
PyCapsule_Destructor¶ カプセルに対するデストラクタコールバック型. 次のように定義されます:
typedef void (*PyCapsule_Destructor)(PyObject *);
PyCapsule_Destructor コールバックの動作については
PyCapsule_New()を参照してください。
-
PyObject*
PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)¶ - Return value: New reference.
pointer を格納する
PyCapsuleを作成します。 pointer 引数は NULL であってはなりません。失敗した場合、例外を設定して NULL を返します。
name 文字列は NULL か、有効なC文字列へのポインタです。NULL で無い場合、この文字列は少なくともカプセルより長く生存する必要があります。(destructor の中で解放することは許可されています)
destructor が NULL で無い場合、カプセルが削除されるときにそのカプセルを引数として呼び出されます。
このカプセルがモジュールの属性として保存される場合、 name は
modulename.attributenameと指定されるべきです。こうすると、他のモジュールがそのカプセルをPyCapsule_Import()でインポートすることができます。
-
void*
PyCapsule_GetPointer(PyObject *capsule, const char *name)¶ カプセルに保存されている pointer を取り出します。失敗した場合は例外を設定して NULL を返します。
name 引数はカプセルに保存されている名前と正確に一致しなければなりません。もしカプセルに格納されている name が NULL なら、この関数の name 引数も同じく NULL でなければなりません。 Python は C言語の
strcmp()を使ってこの name を比較します。
-
PyCapsule_Destructor
PyCapsule_GetDestructor(PyObject *capsule)¶ カプセルに保存されている現在のデストラクタを返します。失敗した場合、例外を設定して NULL を返します。
カプセルは NULL をデストラクタとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。
PyCapsule_IsValid()かPyErr_Occurred()を利用して確認してください。
-
void*
PyCapsule_GetContext(PyObject *capsule)¶ カプセルに保存されている現在のコンテキスト(context)を返します。失敗した場合、例外を設定して NULL を返します。
カプセルは NULL をコンテキストとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。
PyCapsule_IsValid()かPyErr_Occurred()を利用して確認してください。
-
const char*
PyCapsule_GetName(PyObject *capsule)¶ カプセルに保存されている現在の name を返します。失敗した場合、例外を設定して NULL を返します。
カプセルは NULL を name として持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。
PyCapsule_IsValid()かPyErr_Occurred()を利用して確認してください。
-
void*
PyCapsule_Import(const char *name, int no_block)¶ モジュールのカプセル属性から Cオブジェクトへのポインタをインポートします。 name 引数はその属性の完全名を
module.attributeのように指定しなければなりません。カプセルに格納されている name はこの文字列に正確に一致しなければなりません。 no_block が真の時、モジュールを(PyImport_ImportModuleNoBlock()を使って) ブロックせずにインポートします。 no_block が偽の時、モジュールは (PyImport_ImportModule()を使って) 通常の方法でインポートされます。成功した場合、カプセルの内部 ポインタ を返します。失敗した場合、例外を設定して NULL を返します。
-
int
PyCapsule_IsValid(PyObject *capsule, const char *name)¶ capsule が有効なカプセルであるかどうかをチェックします。有効な capsule は、非 NULL で、
PyCapsule_CheckExact()をパスし、非 NULL なポインタを格納していて、内部の name が引数 name とマッチします。 (name の比較方法についてはPyCapsule_GetPointer()を参照)言い換えると、
PyCapsule_IsValid()が真を返す場合、全てのアクセッサ (PyCapsule_Get()で始まる全ての関数) が成功することが保証されます。オブジェクトが有効で name がマッチした場合に非
0を、それ以外の場合に0を返します。この関数は絶対に失敗しません。
-
int
PyCapsule_SetContext(PyObject *capsule, void *context)¶ capsule 内部のコンテキストポインタを context に設定します。
成功したら
0を、失敗したら例外を設定して非0を返します。
-
int
PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)¶ capsule 内部のデストラクタを destructor に設定します。
成功したら
0を、失敗したら例外を設定して非0を返します。