Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 1 | Smart pointers |
| 2 | ############## |
| 3 | |
Dean Moldovan | 5d28dd1 | 2016-10-18 13:56:33 +0200 | [diff] [blame] | 4 | std::unique_ptr |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 5 | =============== |
| 6 | |
| 7 | Given a class ``Example`` with Python bindings, it's possible to return |
| 8 | instances wrapped in C++11 unique pointers, like so |
| 9 | |
| 10 | .. code-block:: cpp |
| 11 | |
| 12 | std::unique_ptr<Example> create_example() { return std::unique_ptr<Example>(new Example()); } |
| 13 | |
| 14 | .. code-block:: cpp |
| 15 | |
| 16 | m.def("create_example", &create_example); |
| 17 | |
| 18 | In other words, there is nothing special that needs to be done. While returning |
| 19 | unique pointers in this way is allowed, it is *illegal* to use them as function |
| 20 | arguments. For instance, the following function signature cannot be processed |
| 21 | by pybind11. |
| 22 | |
| 23 | .. code-block:: cpp |
| 24 | |
| 25 | void do_something_with_example(std::unique_ptr<Example> ex) { ... } |
| 26 | |
| 27 | The above signature would imply that Python needs to give up ownership of an |
| 28 | object that is passed to this function, which is generally not possible (for |
| 29 | instance, the object might be referenced elsewhere). |
| 30 | |
Dean Moldovan | 5d28dd1 | 2016-10-18 13:56:33 +0200 | [diff] [blame] | 31 | std::shared_ptr |
| 32 | =============== |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 33 | |
| 34 | The binding generator for classes, :class:`class_`, can be passed a template |
| 35 | type that denotes a special *holder* type that is used to manage references to |
| 36 | the object. If no such holder type template argument is given, the default for |
| 37 | a type named ``Type`` is ``std::unique_ptr<Type>``, which means that the object |
| 38 | is deallocated when Python's reference count goes to zero. |
| 39 | |
| 40 | It is possible to switch to other types of reference counting wrappers or smart |
| 41 | pointers, which is useful in codebases that rely on them. For instance, the |
| 42 | following snippet causes ``std::shared_ptr`` to be used instead. |
| 43 | |
| 44 | .. code-block:: cpp |
| 45 | |
| 46 | py::class_<Example, std::shared_ptr<Example> /* <- holder type */> obj(m, "Example"); |
| 47 | |
| 48 | Note that any particular class can only be associated with a single holder type. |
| 49 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 50 | One potential stumbling block when using holder types is that they need to be |
| 51 | applied consistently. Can you guess what's broken about the following binding |
| 52 | code? |
| 53 | |
| 54 | .. code-block:: cpp |
| 55 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 56 | class Child { }; |
| 57 | |
| 58 | class Parent { |
| 59 | public: |
| 60 | Parent() : child(std::make_shared<Child>()) { } |
| 61 | Child *get_child() { return child.get(); } /* Hint: ** DON'T DO THIS ** */ |
| 62 | private: |
| 63 | std::shared_ptr<Child> child; |
| 64 | }; |
| 65 | |
| 66 | PYBIND11_PLUGIN(example) { |
| 67 | py::module m("example"); |
| 68 | |
| 69 | py::class_<Child, std::shared_ptr<Child>>(m, "Child"); |
| 70 | |
| 71 | py::class_<Parent, std::shared_ptr<Parent>>(m, "Parent") |
| 72 | .def(py::init<>()) |
| 73 | .def("get_child", &Parent::get_child); |
| 74 | |
| 75 | return m.ptr(); |
| 76 | } |
| 77 | |
| 78 | The following Python code will cause undefined behavior (and likely a |
| 79 | segmentation fault). |
| 80 | |
| 81 | .. code-block:: python |
| 82 | |
| 83 | from example import Parent |
| 84 | print(Parent().get_child()) |
| 85 | |
| 86 | The problem is that ``Parent::get_child()`` returns a pointer to an instance of |
| 87 | ``Child``, but the fact that this instance is already managed by |
| 88 | ``std::shared_ptr<...>`` is lost when passing raw pointers. In this case, |
| 89 | pybind11 will create a second independent ``std::shared_ptr<...>`` that also |
| 90 | claims ownership of the pointer. In the end, the object will be freed **twice** |
| 91 | since these shared pointers have no way of knowing about each other. |
| 92 | |
| 93 | There are two ways to resolve this issue: |
| 94 | |
| 95 | 1. For types that are managed by a smart pointer class, never use raw pointers |
| 96 | in function arguments or return values. In other words: always consistently |
| 97 | wrap pointers into their designated holder types (such as |
| 98 | ``std::shared_ptr<...>``). In this case, the signature of ``get_child()`` |
| 99 | should be modified as follows: |
| 100 | |
| 101 | .. code-block:: cpp |
| 102 | |
| 103 | std::shared_ptr<Child> get_child() { return child; } |
| 104 | |
| 105 | 2. Adjust the definition of ``Child`` by specifying |
| 106 | ``std::enable_shared_from_this<T>`` (see cppreference_ for details) as a |
| 107 | base class. This adds a small bit of information to ``Child`` that allows |
| 108 | pybind11 to realize that there is already an existing |
| 109 | ``std::shared_ptr<...>`` and communicate with it. In this case, the |
| 110 | declaration of ``Child`` should look as follows: |
| 111 | |
| 112 | .. _cppreference: http://en.cppreference.com/w/cpp/memory/enable_shared_from_this |
| 113 | |
| 114 | .. code-block:: cpp |
| 115 | |
| 116 | class Child : public std::enable_shared_from_this<Child> { }; |
| 117 | |
Dean Moldovan | 5d28dd1 | 2016-10-18 13:56:33 +0200 | [diff] [blame] | 118 | .. _smart_pointers: |
| 119 | |
| 120 | Custom smart pointers |
| 121 | ===================== |
| 122 | |
| 123 | pybind11 supports ``std::unique_ptr`` and ``std::shared_ptr`` right out of the |
| 124 | box. For any other custom smart pointer, transparent conversions can be enabled |
| 125 | using a macro invocation similar to the following. It must be declared at the |
Wenzel Jakob | 2029171 | 2016-12-15 23:44:23 +0100 | [diff] [blame] | 126 | top namespace level before any binding code: |
Dean Moldovan | 5d28dd1 | 2016-10-18 13:56:33 +0200 | [diff] [blame] | 127 | |
| 128 | .. code-block:: cpp |
| 129 | |
| 130 | PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>); |
| 131 | |
| 132 | The first argument of :func:`PYBIND11_DECLARE_HOLDER_TYPE` should be a |
| 133 | placeholder name that is used as a template parameter of the second argument. |
| 134 | Thus, feel free to use any identifier, but use it consistently on both sides; |
| 135 | also, don't use the name of a type that already exists in your codebase. |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 136 | |
Wenzel Jakob | 2029171 | 2016-12-15 23:44:23 +0100 | [diff] [blame] | 137 | The macro also accepts a third optional boolean parameter that is set to false |
| 138 | by default. Specify |
| 139 | |
| 140 | .. code-block:: cpp |
| 141 | |
| 142 | PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>, true); |
| 143 | |
| 144 | if ``SmartPtr<T>`` can always be initialized from a ``T*`` pointer without the |
| 145 | risk of inconsistencies (such as multiple independent ``SmartPtr`` instances |
| 146 | believing that they are the sole owner of the ``T*`` pointer). A common |
| 147 | situation where ``true`` should be passed is when the ``T`` instances use |
| 148 | *intrusive* reference counting. |
| 149 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 150 | Please take a look at the :ref:`macro_notes` before using this feature. |
| 151 | |
Dean Moldovan | ec009a7 | 2017-01-31 17:05:44 +0100 | [diff] [blame] | 152 | By default, pybind11 assumes that your custom smart pointer has a standard |
| 153 | interface, i.e. provides a ``.get()`` member function to access the underlying |
| 154 | raw pointer. If this is not the case, pybind11's ``holder_helper`` must be |
| 155 | specialized: |
| 156 | |
| 157 | .. code-block:: cpp |
| 158 | |
| 159 | // Always needed for custom holder types |
| 160 | PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>); |
| 161 | |
| 162 | // Only needed if the type's `.get()` goes by another name |
| 163 | namespace pybind11 { namespace detail { |
| 164 | template <typename T> |
| 165 | struct holder_helper<SmartPtr<T>> { // <-- specialization |
| 166 | static const T *get(const SmartPtr<T> &p) { return p.getPointer(); } |
| 167 | }; |
| 168 | }} |
| 169 | |
| 170 | The above specialization informs pybind11 that the custom ``SmartPtr`` class |
| 171 | provides ``.get()`` functionality via ``.getPointer()``. |
| 172 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 173 | .. seealso:: |
| 174 | |
| 175 | The file :file:`tests/test_smart_ptr.cpp` contains a complete example |
| 176 | that demonstrates how to work with custom reference-counting holder types |
| 177 | in more detail. |