]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [section boost/python/ptr.hpp] |
2 | [section Introduction] | |
3 | <boost/python/ptr.hpp> defines the ptr() function template, which allows users to specify how to convert C++ pointer values to python in the context of implementing overridable virtual functions, invoking Python callable objects, or explicitly converting C++ objects to Python. Normally, when passing pointers to Python callbacks, the pointee is copied to ensure that the Python object never holds a dangling reference. To specify that the new Python object should merely contain a copy of a pointer p, the user can pass ptr(p) instead of passing p directly. This interface is meant to mirror the use of boost::ref(), which can be similarly used to prevent copying of referents. | |
4 | ||
5 | ptr(p) returns an instance of [link function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper `pointer_wrapper<>`], which can be detected using the [link function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe `is_pointer_wrapper<>`] metafunction; [link function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer `unwrap_pointer<>`] is a metafunction which extracts the original pointer type from a `pointer_wrapper<>`. These classes can be thought of as implementation details. | |
6 | [endsect] | |
7 | [section Functions] | |
8 | `` | |
9 | template <class T> | |
10 | pointer_wrapper<T> ptr(T x); | |
11 | `` | |
12 | [variablelist | |
13 | [[Requires][T is a pointer type.]] | |
14 | [[Returns][pointer_wrapper<T>(x)]] | |
15 | [[Throws][nothing.]] | |
16 | ] | |
17 | [endsect] | |
18 | [section Class template `pointer_wrapper`] | |
19 | A "type envelope" which is returned by `ptr()`, used to indicate reference semantics for pointers passed to Python callbacks. | |
20 | `` | |
21 | namespace boost { namespace python | |
22 | { | |
23 | template<class Ptr> class pointer_wrapper | |
24 | { | |
25 | public: | |
26 | typedef Ptr type; | |
27 | ||
28 | explicit pointer_wrapper(Ptr x); | |
29 | operator Ptr() const; | |
30 | Ptr get() const; | |
31 | }; | |
32 | }} | |
33 | `` | |
34 | [endsect] | |
35 | [section Class template `pointer_wrapper` types] | |
36 | `` | |
37 | typedef Ptr type; | |
38 | `` | |
39 | The type of the pointer being wrapped. | |
40 | [endsect] | |
41 | [section Class template `pointer_wrapper` constructors and destructor] | |
42 | `` | |
43 | explicit pointer_wrapper(Ptr x); | |
44 | `` | |
45 | [variablelist | |
46 | [[Requires][`Ptr` is a pointer type]] | |
47 | [[Effects][Stores `x` in a the `pointer_wrapper<>`. ]] | |
48 | [[Throws][nothing.]] | |
49 | ] | |
50 | [endsect] | |
51 | [section Class template `pointer_wrapper` observer functions] | |
52 | `` | |
53 | operator Ptr() const; | |
54 | Ptr get() const; | |
55 | `` | |
56 | [variablelist | |
57 | [[Returns][a copy of the stored pointer. ]] | |
58 | [[Rationale][pointer_wrapper is intended to be a stand-in for the actual pointer type, but sometimes it's better to have an explicit way to retrieve the pointer. ]] | |
59 | ] | |
60 | [endsect] | |
61 | [section Metafunctions] | |
62 | [section Class template `is_pointer_wrapper`] | |
63 | A unary metafunction whose value is true iff its argument is a pointer_wrapper<>. | |
64 | `` | |
65 | namespace boost { namespace python | |
66 | { | |
67 | template<class T> class is_pointer_wrapper | |
68 | { | |
69 | static unspecified value = ...; | |
70 | }; | |
71 | }} | |
72 | `` | |
73 | [variablelist | |
74 | [[Returns][`true` iff `T` is a specialization of `pointer_wrapper<>`. | |
75 | value is an integral constant convertible to bool of unspecified type ]] | |
76 | ] | |
77 | [endsect] | |
78 | [section Class template `unwrap_pointer`] | |
79 | A unary metafunction which extracts the wrapped pointer type from a specialization of pointer_wrapper<>. | |
80 | `` | |
81 | namespace boost { namespace python | |
82 | { | |
83 | template<class T> class unwrap_pointer | |
84 | { | |
85 | typedef unspecified type; | |
86 | }; | |
87 | }} | |
88 | `` | |
89 | [variablelist | |
90 | [[Returns][`T::type` if `T` is a specialization of `pointer_wrapper<>`, `T` otherwise ]] | |
91 | ] | |
92 | [endsect] | |
93 | [endsect] | |
94 | [section Example] | |
95 | This example illustrates the use of ptr() to prevent an object from being copied: | |
96 | `` | |
97 | #include <boost/python/call.hpp> | |
98 | #include <boost/python/ptr.hpp> | |
99 | ||
100 | class expensive_to_copy | |
101 | { | |
102 | ... | |
103 | }; | |
104 | ||
105 | void pass_as_arg(expensive_to_copy* x, PyObject* f) | |
106 | { | |
107 | // call the Python function f, passing a Python object built around | |
108 | // which refers to *x by-pointer. | |
109 | // | |
110 | // *** Note: ensuring that *x outlives the argument to f() is *** | |
111 | // *** up to the user! Failure to do so could result in a crash! *** | |
112 | ||
113 | boost::python::call<void>(f, ptr(x)); | |
114 | } | |
115 | ... | |
116 | `` | |
117 | [endsect] | |
118 | [endsect] |