mirror of
https://github.com/pybind/pybind11.git
synced 2024-11-11 08:03:55 +00:00
doc updates
This commit is contained in:
parent
09e22b4a17
commit
f53e300fbd
@ -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,14 +526,13 @@ 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.
|
||||
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::
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user