119 lines
4.0 KiB
Plaintext
119 lines
4.0 KiB
Plaintext
[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]
|