]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [section boost/python/register_ptr_to_python.hpp] |
2 | [section Introduction] | |
3 | <boost/python/register_ptr_to_python.hpp> supplies `register_ptr_to_python`, a function template which registers a conversion for smart pointers to Python. The resulting Python object holds a copy of the converted smart pointer, but behaves as though it were a wrapped copy of the pointee. If the pointee type has virtual functions and the class representing its dynamic (most-derived) type has been wrapped, the Python object will be an instance of the wrapper for the most-derived type. More than one smart pointer type for a pointee's class can be registered. | |
4 | ||
5 | Note that in order to convert a Python `X` object to a `smart_ptr<X>&` (non-const reference), the embedded C++ object must be held by `smart_ptr<X>`, and that when wrapped objects are created by calling the constructor from Python, how they are held is determined by the HeldType parameter to `class_<...>` instances. | |
6 | [endsect] | |
7 | [section Function `register_ptr_to_python`] | |
8 | `` | |
9 | template <class P> | |
10 | void register_ptr_to_python() | |
11 | `` | |
12 | [variablelist | |
13 | [[Requires][`P` is [link concepts.dereferenceable Dereferenceable].]] | |
14 | [[Effects][Allows conversions to-python of P instances. ]] | |
15 | ] | |
16 | [endsect] | |
17 | [section Example] | |
18 | Here is an example of a module that contains a class A with virtual functions and some functions that work with boost::shared_ptr<A>. | |
19 | ||
20 | In C++: | |
21 | `` | |
22 | struct A | |
23 | { | |
24 | virtual int f() { return 0; } | |
25 | }; | |
26 | ||
27 | shared_ptr<A> New() { return shared_ptr<A>( new A() ); } | |
28 | ||
29 | int Ok( const shared_ptr<A>& a ) { return a->f(); } | |
30 | ||
31 | int Fail( shared_ptr<A>& a ) { return a->f(); } | |
32 | ||
33 | struct A_Wrapper: A | |
34 | { | |
35 | A_Wrapper(PyObject* self_): self(self_) {} | |
36 | int f() { return call_method<int>(self, "f"); } | |
37 | int default_f() { return A::f(); } | |
38 | PyObject* self; | |
39 | }; | |
40 | ||
41 | BOOST_PYTHON_MODULE(register_ptr) | |
42 | { | |
43 | class_<A, A_Wrapper>("A") | |
44 | .def("f", &A::f, &A_Wrapper::default_f) | |
45 | ; | |
46 | ||
47 | def("New", &New); | |
48 | def("Ok", &Call); | |
49 | def("Fail", &Fail); | |
50 | ||
51 | register_ptr_to_python< shared_ptr<A> >(); | |
52 | } | |
53 | `` | |
54 | In Python: | |
55 | `` | |
56 | >>> from register_ptr import * | |
57 | >>> a = A() | |
58 | >>> Ok(a) # ok, passed as shared_ptr<A> | |
59 | 0 | |
60 | >>> Fail(a) # passed as shared_ptr<A>&, and was created in Python! | |
61 | Traceback (most recent call last): | |
62 | File "<stdin>", line 1, in ? | |
63 | TypeError: bad argument type for built-in operation | |
64 | >>> | |
65 | >>> na = New() # now "na" is actually a shared_ptr<A> | |
66 | >>> Ok(a) | |
67 | 0 | |
68 | >>> Fail(a) | |
69 | 0 | |
70 | >>> | |
71 | `` | |
72 | If shared_ptr<A> is registered as follows: | |
73 | `` | |
74 | class_<A, A_Wrapper, shared_ptr<A> >("A") | |
75 | .def("f", &A::f, &A_Wrapper::default_f) | |
76 | ; | |
77 | `` | |
78 | There will be an error when trying to convert shared_ptr<A> to shared_ptr<A_Wrapper>: | |
79 | `` | |
80 | >>> a = New() | |
81 | Traceback (most recent call last): | |
82 | File "<stdin>", line 1, in ? | |
83 | TypeError: No to_python (by-value) converter found for C++ type: class boost::shared_ptr<struct A> | |
84 | >>> | |
85 | `` | |
86 | [endsect] |