From 717df7523743f66f70e20db2b0e87e51230f302b Mon Sep 17 00:00:00 2001 From: nafur Date: Tue, 28 Jun 2016 18:07:11 +0200 Subject: [PATCH] Added warning about same-address-optimization See https://github.com/pybind/pybind11/issues/254 --- docs/advanced.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index f5b48d4d7..366f06d8f 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -468,7 +468,7 @@ functions. The default policy is :enum:`return_value_policy::automatic`. | :enum:`return_value_policy::take_ownership` | Reference an existing object (i.e. do not create a new copy) and take | | | ownership. Python will call the destructor and delete operator when the | | | object's reference count reaches zero. Undefined behavior ensues when the | -| | C++ side does the same.. | +| | C++ side does the same. | +--------------------------------------------------+----------------------------------------------------------------------------+ | :enum:`return_value_policy::copy` | Create a new copy of the returned object, which will be owned by Python. | | | This policy is comparably safe because the lifetimes of the two instances | @@ -526,6 +526,15 @@ The following example snippet shows a use case of the non-determinism and segmentation faults, hence it is worth spending the time to understand all the different options in the table above. +.. warning:: + + pybind11 tries to eliminate duplicate addresses by returning the same reference object. + If two addresses are the same, though they do not point to the same object semantically, + this may cause unexpected behaviour. An explicit policy should be used instead of + relying on `automatic`. + A common example is a reference to the first member of a class which has the same memory + location as its owning class. + .. note:: The next section on :ref:`call_policies` discusses *call policies* that can be