123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118 |
- [section boost/python/ptr.hpp]
- [section Introduction]
- <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.
- 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.
- [endsect]
- [section Functions]
- ``
- template <class T>
- pointer_wrapper<T> ptr(T x);
- ``
- [variablelist
- [[Requires][T is a pointer type.]]
- [[Returns][pointer_wrapper<T>(x)]]
- [[Throws][nothing.]]
- ]
- [endsect]
- [section Class template `pointer_wrapper`]
- A "type envelope" which is returned by `ptr()`, used to indicate reference semantics for pointers passed to Python callbacks.
- ``
- 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;
- };
- }}
- ``
- [endsect]
- [section Class template `pointer_wrapper` types]
- ``
- typedef Ptr type;
- ``
- The type of the pointer being wrapped.
- [endsect]
- [section Class template `pointer_wrapper` constructors and destructor]
- ``
- explicit pointer_wrapper(Ptr x);
- ``
- [variablelist
- [[Requires][`Ptr` is a pointer type]]
- [[Effects][Stores `x` in a the `pointer_wrapper<>`. ]]
- [[Throws][nothing.]]
- ]
- [endsect]
- [section Class template `pointer_wrapper` observer functions]
- ``
- operator Ptr() const;
- Ptr get() const;
- ``
- [variablelist
- [[Returns][a copy of the stored pointer. ]]
- [[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. ]]
- ]
- [endsect]
- [section Metafunctions]
- [section Class template `is_pointer_wrapper`]
- A unary metafunction whose value is true iff its argument is a pointer_wrapper<>.
- ``
- namespace boost { namespace python
- {
- template<class T> class is_pointer_wrapper
- {
- static unspecified value = ...;
- };
- }}
- ``
- [variablelist
- [[Returns][`true` iff `T` is a specialization of `pointer_wrapper<>`.
- value is an integral constant convertible to bool of unspecified type ]]
- ]
- [endsect]
- [section Class template `unwrap_pointer`]
- A unary metafunction which extracts the wrapped pointer type from a specialization of pointer_wrapper<>.
- ``
- namespace boost { namespace python
- {
- template<class T> class unwrap_pointer
- {
- typedef unspecified type;
- };
- }}
- ``
- [variablelist
- [[Returns][`T::type` if `T` is a specialization of `pointer_wrapper<>`, `T` otherwise ]]
- ]
- [endsect]
- [endsect]
- [section Example]
- This example illustrates the use of ptr() to prevent an object from being copied:
- ``
- #include <boost/python/call.hpp>
- #include <boost/python/ptr.hpp>
- class expensive_to_copy
- {
- ...
- };
- void pass_as_arg(expensive_to_copy* x, PyObject* f)
- {
- // call the Python function f, passing a Python object built around
- // which refers to *x by-pointer.
- //
- // *** Note: ensuring that *x outlives the argument to f() is ***
- // *** up to the user! Failure to do so could result in a crash! ***
- boost::python::call<void>(f, ptr(x));
- }
- ...
- ``
- [endsect]
- [endsect]
|