pytho****@googl*****
pytho****@googl*****
2011年 11月 8日 (火) 13:58:12 JST
Revision: de39a0e62bdc Author: Naoki INADA <inada****@klab*****> Date: Mon Nov 7 20:52:47 2011 Log: New 2.7.2: c-api/capsule.rst http://code.google.com/p/python-doc-ja/source/detail?r=de39a0e62bdc Modified: /c-api/capsule.rst ======================================= --- /c-api/capsule.rst Fri Oct 28 23:01:19 2011 +++ /c-api/capsule.rst Mon Nov 7 20:52:47 2011 @@ -2,149 +2,150 @@ .. _capsules: -Capsules --------- +カプセル (Capsules) +--------------------- .. index:: object: Capsule -Refer to :ref:`using-capsules` for more information on using these objects. +`using-capsules` 以下のオブジェクトを使う方法について は :ref:`using-capsules` +を参照してください。 .. ctype:: PyCapsule - This subtype of :ctype:`PyObject` represents an opaque value, useful for C - extension modules who need to pass an opaque value (as a :ctype:`void\*` - pointer) through Python code to other C code. It is often used to make a C - function pointer defined in one module available to other modules, so the - regular import mechanism can be used to access C APIs defined in dynamically - loaded modules. + この :ctype:`PyObject` のサブタイプは、任意の値を表し、C拡張モジュールか ら + Pythonコードを経由して他のC言語のコードに任意の値を(:ctype:`void\*` ポイ ンタ + の形で)渡す必要があるときに有用です。 + あるモジュール内で定義されているC言語関数のポインタを、他のモジュールに 渡して + そこから呼び出せるようにするためによく使われます。これにより、動的にロー ドされる + モジュールの中の C API に通常の import 機構を通してアクセスすることがで きます。 .. ctype:: PyCapsule_Destructor - The type of a destructor callback for a capsule. Defined as:: + カプセルに対するデストラクタコールバック型. 次のように定義されます:: typedef void (*PyCapsule_Destructor)(PyObject *); - See :cfunc:`PyCapsule_New` for the semantics of PyCapsule_Destructor - callbacks. + PyCapsule_Destructor コールバックの動作については :cfunc:`PyCapsule_New` + を参照してください。 .. cfunction:: int PyCapsule_CheckExact(PyObject *p) - Return true if its argument is a :ctype:`PyCapsule`. + 引数が :ctype:`PyCapsule` だったときに true を返します。 .. cfunction:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor) - Create a :ctype:`PyCapsule` encapsulating the *pointer*. The *pointer* - argument may not be *NULL*. - - On failure, set an exception and return *NULL*. - - The *name* string may either be *NULL* or a pointer to a valid C string. If - non-*NULL*, this string must outlive the capsule. (Though it is permitted to - free it inside the *destructor*.) - - If the *destructor* argument is not *NULL*, it will be called with the - capsule as its argument when it is destroyed. - - If this capsule will be stored as an attribute of a module, the *name* should - be specified as ``modulename.attributename``. This will enable other modules - to import the capsule using :cfunc:`PyCapsule_Import`. + *pointer* を格納する :ctype:`PyCapsule` を作成します。 + *pointer* 引数は *NULL* であってはなりません。 + + 失敗した場合、例外を設定して *NULL* を返します。 + + *name* 文字列は *NULL* か、有効なC文字列へのポインタです。 + *NULL* で無い場合、この文字列は少なくともカプセルより長く生存する必要が あります。 + (*destructor* の中で解放することは許可されています) + + *destructor* が *NULL* で無い場合、カプセルが削除されるときにそのカプセ ルを + 引数として呼び出されます。 + + このカプセルがモジュールの属性として保存される場合、 *name* は + ``modulename.attributename`` と指定されるべきです。 + こうすると、他のモジュールがそのカプセルを :cfunc:`PyCapsule_Import` で + インポートすることができます。 .. cfunction:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name) - Retrieve the *pointer* stored in the capsule. On failure, set an exception - and return *NULL*. - - The *name* parameter must compare exactly to the name stored in the capsule. - If the name stored in the capsule is *NULL*, the *name* passed in must also - be *NULL*. Python uses the C function :cfunc:`strcmp` to compare capsule - names. + カプセルに保存されている *pointer* を取り出します。失敗した場合は + 例外を設定して *NULL* を返します。 + + *name* 引数はカプセルに保存されている名前と正確に一致しなければなりませ ん。 + もしカプセルに格納されている name が *NULL* なら、この関数の *name* 引数 も + 同じく *NULL* でなければなりません。 Python は C言語の :cfunc:`strcmp` + を使ってこの name を比較します。 .. cfunction:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule) - Return the current destructor stored in the capsule. On failure, set an - exception and return *NULL*. - - It is legal for a capsule to have a *NULL* destructor. This makes a *NULL* - return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or - :cfunc:`PyErr_Occurred` to disambiguate. + カプセルに保存されている現在のデストラクタを返します。 + 失敗した場合、例外を設定して *NULL* を返します。 + + カプセルは *NULL* をデストラクタとして持つことができます。 + 従って、戻り値の *NULL* がエラーを指してない可能性があります。 + :cfunc:`PyCapsule_IsValid` か `PyErr_Occurred` を利用して確認してくださ い。 .. cfunction:: void* PyCapsule_GetContext(PyObject *capsule) - Return the current context stored in the capsule. On failure, set an - exception and return *NULL*. - - It is legal for a capsule to have a *NULL* context. This makes a *NULL* - return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or - :cfunc:`PyErr_Occurred` to disambiguate. + カプセルに保存されている現在のコンテキスト(context)を返します。 + 失敗した場合、例外を設定して *NULL* を返します。 + + カプセルは *NULL* をコンテキストとして持つことができます。 + 従って、戻り値の *NULL* がエラーを指してない可能性があります。 + :cfunc:`PyCapsule_IsValid` か `PyErr_Occurred` を利用して確認してくださ い。 .. cfunction:: const char* PyCapsule_GetName(PyObject *capsule) - Return the current name stored in the capsule. On failure, set an exception - and return *NULL*. - - It is legal for a capsule to have a *NULL* name. This makes a *NULL* return - code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or - :cfunc:`PyErr_Occurred` to disambiguate. + カプセルに保存されている現在の name を返します。 + 失敗した場合、例外を設定して *NULL* を返します。 + + カプセルは *NULL* を name として持つことができます。 + 従って、戻り値の *NULL* がエラーを指してない可能性があります。 + :cfunc:`PyCapsule_IsValid` か `PyErr_Occurred` を利用して確認してくださ い。 .. cfunction:: void* PyCapsule_Import(const char *name, int no_block) - Import a pointer to a C object from a capsule attribute in a module. The - *name* parameter should specify the full name to the attribute, as in - ``module.attribute``. The *name* stored in the capsule must match this - string exactly. If *no_block* is true, import the module without blocking - (using :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false, - import the module conventionally (using :cfunc:`PyImport_ImportModule`). - - Return the capsule's internal *pointer* on success. On failure, set an - exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to - import the module, and *no_block* was true, no exception is set. + モジュールのカプセル属性から Cオブジェクトへのポインタをインポートしま す。 + *name* 引数はその属性の完全名を ``module.attribute`` のように指定しなけ ればなりません。 + カプセルに格納されている *name* はこの文字列に正確に一致しなければなりま せん。 + *no_block* が真の時、モジュールを(:cfunc:`PyImport_InportModuleNoBlock` を使って) + ブロックせずにインポートします。 *no_block* が偽の時、モジュールは (:cfunc:`PyImport_ImportModule` + を使って) 通常の方法でインポートされます。 + + 成功した場合、カプセル内部の *pointer* を返します。 + 失敗した場合、例外を設定して *NULL* を返します。ただし、 *no_block* が真 だった場合は、 + :cfunc:`PyCapsule_Import` はモジュールのインポートに失敗しても例外を設定 しません。 .. cfunction:: int PyCapsule_IsValid(PyObject *capsule, const char *name) - Determines whether or not *capsule* is a valid capsule. A valid capsule is - non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-*NULL* pointer - stored in it, and its internal name matches the *name* parameter. (See - :cfunc:`PyCapsule_GetPointer` for information on how capsule names are - compared.) - - In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to - any of the accessors (any function starting with :cfunc:`PyCapsule_Get`) are - guaranteed to succeed. - - Return a nonzero value if the object is valid and matches the name passed in. - Return 0 otherwise. This function will not fail. + *capsule* が有効なカプセルであるかどうかをチェックします。 + 有効な *capsule* は、非 *NULL* で、 :cfunc:`PyCapsule_CheckExact` をパス し、 + 非 *NULL* なポインタを格納していて、内部の name が引数 *name* とマッチし ます。 + (name の比較方法については :cfunc:`PyCapsule_GetPointer` を参照) + + 言い換えると、 :cfunc:`PyCapsule_IsValid` が真を返す場合、全てのアクセッ サ + (:cfunc:`PyCapsule_Get` で始まる全ての関数) が成功することが保証されま す。 + + オブジェクトが有効で name がマッチした場合に非0を、それ以外の場合に 0 を 返します。 + この関数は絶対に失敗しません。 .. cfunction:: int PyCapsule_SetContext(PyObject *capsule, void *context) - Set the context pointer inside *capsule* to *context*. - - Return 0 on success. Return nonzero and set an exception on failure. + *capsule* 内部のコンテキストポインタを *context* に設定します。 + + 成功したら 0 を、失敗したら例外を設定して 非0 を返します。 .. cfunction:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor) - Set the destructor inside *capsule* to *destructor*. - - Return 0 on success. Return nonzero and set an exception on failure. + *capsule* 内部のデストラクタを *destructor* に設定します。 + + 成功したら 0 を、失敗したら例外を設定して 非0 を返します。 .. cfunction:: int PyCapsule_SetName(PyObject *capsule, const char *name) - Set the name inside *capsule* to *name*. If non-*NULL*, the name must - outlive the capsule. If the previous *name* stored in the capsule was not - *NULL*, no attempt is made to free it. - - Return 0 on success. Return nonzero and set an exception on failure. + *capsule* 内部の name を *name* に設定します。 *name* が非 *NULL* のと き、 + それは *capsule* よりも長い寿命を持つ必要があります。 + もしすでに *capsule* に非 *NULL* の *name* が保存されていた場合、それに 対する + 開放は行われません。 + + 成功したら 0 を、失敗したら例外を設定して 非0 を返します。 .. cfunction:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer) - Set the void pointer inside *capsule* to *pointer*. The pointer may not be - *NULL*. - - Return 0 on success. Return nonzero and set an exception on failure. + *capsule* 内部のポインタを *pointer* に設定します。 *pointer* は *NULL* + であってはなりません。 + + 成功したら 0 を、失敗したら例外を設定して 非0 を返します。
