mirror of
https://github.com/pybind/pybind11.git
synced 2024-11-14 17:43:53 +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 |
|
| :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,14 +526,13 @@ 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::
|
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
|
||||||
pybind11 tries to eliminate duplicate addresses by returning the same reference object.
|
case, the class and attribute will be located at the same address in
|
||||||
If two addresses are the same, though they do not point to the same object semantically,
|
memory, which pybind11 will recongnize and return the parent instance
|
||||||
this may cause unexpected behaviour. An explicit policy should be used instead of
|
instead of creating a new Python object that represents the attribute.
|
||||||
relying on `automatic`.
|
Here, the :enum:`return_value_policy::reference_internal` policy should be
|
||||||
A common example is a reference to the first member of a class which has the same memory
|
used rather than relying on the automatic one.
|
||||||
location as its owning class.
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user