boost/python/ptr.hpp

はじめに

<boost/python/ptr.hpp>ptr 関数テンプレートを定義する。これによりオーバーライド可能な仮想関数の実装、Python の呼び出し可能オブジェクトの起動、あるいは C++ オブジェクトから Python への明示的な変換において C++ のポインタ値を Python に変換する方法を指定できる。通常、Python のコールバックにポインタを渡すと、Python のオブジェクトが懸垂参照を保持しないようポインタ先はコピーされる。新しい Python のオブジェクトが単にポインタ p のコピーを持つべきだということを指定するには、ユーザは p を直接渡すのではなく ptr(p) を渡すようにする。このインターフェイスは同様に参照のコピーを抑止する boost::ref() の類似品である。

ptr(p) は is_pointer_wrapper<> メタ関数で検出可能な pointer_wrapper<> のインスタンスを返す。unwrap_pointer<>pointer_wrapper<> から元のポインタ型を抽出するメタ関数である。これらのクラスは実装の詳細と考えてよい。

ptr

template<class T>
pointer_wrapper<T> ptr(T x)
要件

T がポインタ型。

戻り値

pointer_wrapper<T>(x)

例外

なし。

クラス

pointer_wrapper クラステンプレート

template<class Ptr>
class pointer_wrapper

ptr が返す「型の封筒(envelope)」であり、Python のコールバックへ渡すポインタの参照セマンティクスを示すのに使用する。

pointer_wrapper クラステンプレートの概要

namespace boost { namespace python
{
    template<class Ptr> class pointer_wrapper
    {
     public:
        typedef Ptr type;

        explicit pointer_wrapper(Ptr x);
        operator Ptr() const;
        Ptr get() const;
    };
}}

pointer_wrapper クラステンプレートの型

typedef Ptr type

ラップするポインタの型。

pointer_wrapper クラステンプレートのコンストラクタおよびデストラクタ

explicit pointer_wrapper(Ptr x)
要件

Ptr がポインタ型。

効果

pointer_wrapper<>x を格納する。

例外

なし。

pointer_wrapper クラステンプレートのオブザーバ関数

operator Ptr() const
Ptr get() const
戻り値

格納しているポインタのコピー。

根拠

pointer_wrapper<> は実際のポインタ型の代理を意図しているが、時にはポインタを取得する明示的な方法があったほうがよい。

メタ関数

is_pointer_wrapper クラステンプレート

template<class T>
class is_pointer_wrapper

引数が pointer_wrapper<> である場合に value が真となる単項メタ関数。

戻り値

Tpointer_wrapper<> の特殊化であれば truevalue は未規定型の論理値へ変換可能な整数定数。

is_pointer_wrapper クラステンプレートの概要

namespace boost { namespace python
{
    template<class T> class is_pointer_wrapper
    {
        static unspecified value = ...;
    };
}}

unwrap_pointer クラステンプレート

template<class T>
class unwrap_pointer

pointer_wrapper<> の特殊化からラップしたポインタ型を抽出する単項メタ関数。

Returns

Tpointer_wrapper<> の特殊化の場合、T::type。それ以外の場合は T

unwrap_pointer クラステンプレートの概要

namespace boost { namespace python
{
    template<class T> class unwrap_pointer
    {
        typedef unspecified type;
    };
}}

ptr を使用してオブジェクトのコピーを抑止する例。

#include <boost/python/call.hpp>
#include <boost/python/ptr.hpp>

class expensive_to_copy
{
   ...
};

void pass_as_arg(expensive_to_copy* x, PyObject* f)
{
   // Python の関数 f を呼び出し、*x を「ポインタで」参照する
   // Python オブジェクトを渡す。
   //
   // *** 注意:*x を f() の引数として使用した後も延命させるのは ***
   // *** ユーザの責任である!失敗するとクラッシュする!         ***

   boost::python::call<void>(f, ptr(x));
}
...