Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-25 14:45:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added warning about same-address-optimization

Browse Source 
See https://github.com/pybind/pybind11/issues/254
This commit is contained in:
nafur 2016-06-28 18:07:11 +02:00 committed by GitHub
parent 2353b9b8fa
commit 717df75237
1 changed files with 10 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/advanced.rst
View File

@ -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 | | :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 | | | ownership. Python will call the destructor and delete operator when the |
| | object's reference count reaches zero. Undefined behavior ensues 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. | | :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 | | | 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 non-determinism and segmentation faults, hence it is worth spending the
time to understand all the different options in the table above. 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:: .. note::
The next section on :ref:`call_policies` discusses *call policies* that can be The next section on :ref:`call_policies` discusses *call policies* that can be