return value policy clarifications
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 9054f91..26046e1 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -507,8 +507,59 @@
| | policy described next. |
+--------------------------------------------------+----------------------------------------------------------------------------+
-The following example snippet shows a use case of the
-:enum:`return_value_policy::reference_internal` policy.
+.. warning::
+
+ Code with invalid call policies might access unitialized memory or free
+ data structures multiple times, which can lead to hard-to-debug
+ non-determinism and segmentation faults, hence it is worth spending the
+ time to understand all the different options in the table above.
+
+One important aspect regarding the above policies is that they only apply to
+instances which pybind11 has *not* seen before, in which case the policy
+clarifies essential questions about the return value's lifetime and ownership.
+
+When pybind11 knows the instance already (as identified via its address in
+memory), it will return the existing Python object wrapper rather than creating
+a copy. This means that functions which merely cast a reference (or pointer)
+into a different type don't do what one would expect:
+
+.. code-block:: cpp
+
+ A &func(B &value) { return (A&) value; }
+
+The wrapped version of this function will return the original ``B`` instance.
+To force a cast, the argument should be returned by value.
+
+More common (and equally problematic) are cases where methods (e.g. getters)
+return a pointer or reference to the first attribute of a class.
+
+.. code-block:: cpp
+ :emphasize-lines: 3, 13
+
+ class Example {
+ public:
+ Internal &get_internal() { return internal; }
+ private:
+ Internal internal;
+ };
+
+ PYBIND11_PLUGIN(example) {
+ py::module m("example", "pybind11 example plugin");
+
+ py::class_<Example>(m, "Example")
+ .def(py::init<>())
+ .def("get_internal", &Example::get_internal); /* Note: don't do this! */
+
+ return m.ptr();
+ }
+
+As in the above casting example, the instance and its attribute will be located
+at the same address in memory, which pybind11 will recongnize and return the
+parent instance instead of creating a new Python object that represents the
+attribute. The special :enum:`return_value_policy::reference_internal` policy
+should be used in this case: it disables the same-address optimization and
+ensures that pybind11 returns a reference.
+The following example snippet shows the correct usage:
.. code-block:: cpp
@@ -530,20 +581,7 @@
return m.ptr();
}
-.. warning::
- Code with invalid call policies might access unitialized memory or free
- data structures multiple times, which can lead to hard-to-debug
- non-determinism and segmentation faults, hence it is worth spending the
- time to understand all the different options in the table above.
-
- It is worth highlighting one common issue where a method (e.g. a getter)
- returns a reference (or pointer) to the first attribute of a class. In this
- case, the class and attribute will be located at the same address in
- memory, which pybind11 will recongnize and return the parent instance
- instead of creating a new Python object that represents the attribute.
- Here, the :enum:`return_value_policy::reference_internal` policy should be
- used rather than relying on the automatic one.
.. note::