From e84f557edf7c703bb4e1af912ab5a04a22a8d7ea Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Tue, 26 Apr 2016 23:19:19 +0200 Subject: [PATCH] documentation improvements --- docs/_static/theme_overrides.css | 4 ++ docs/advanced.rst | 77 ++++++++++++++++++-------------- docs/basics.rst | 4 +- docs/changelog.rst | 4 +- docs/conf.py | 2 +- docs/faq.rst | 2 +- include/pybind11/common.h | 20 ++++++--- 7 files changed, 67 insertions(+), 46 deletions(-) diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css index f678ab548..1071809fa 100644 --- a/docs/_static/theme_overrides.css +++ b/docs/_static/theme_overrides.css @@ -5,3 +5,7 @@ .rst-content table.docutils td { vertical-align: top !important; } +div[class^='highlight'] pre { + white-space: pre; + white-space: pre-wrap; +} diff --git a/docs/advanced.rst b/docs/advanced.rst index 534a0f2e4..1c6f6e0a9 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -416,12 +416,12 @@ functions. The default policy is :enum:`return_value_policy::automatic`. +==================================================+============================================================================+ | :enum:`return_value_policy::automatic` | This is the default return value policy, which falls back to the policy | | | :enum:`return_value_policy::take_ownership` when the return value is a | -| | pointer. Otherwise, it uses :enum::`return_value::move` or | -| | :enum::`return_value::copy` for rvalue and lvalue references, respectively.| +| | pointer. Otherwise, it uses :enum:`return_value::move` or | +| | :enum:`return_value::copy` for rvalue and lvalue references, respectively. | | | See below for a description of what all of these different policies do. | +--------------------------------------------------+----------------------------------------------------------------------------+ | :enum:`return_value_policy::automatic_reference` | As above, but use policy :enum:`return_value_policy::reference` when the | -| | return value is a pointer. | +| | return value is a pointer. You probably won't need to use this. | +--------------------------------------------------+----------------------------------------------------------------------------+ | :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 | @@ -439,36 +439,22 @@ functions. The default policy is :enum:`return_value_policy::automatic`. | :enum:`return_value_policy::reference` | Reference an existing object, but do not take ownership. The C++ side is | | | responsible for managing the object's lifetime and deallocating it when | | | it is no longer used. Warning: undefined behavior will ensue when the C++ | -| | side deletes an object that is still referenced by Python. | +| | side deletes an object that is still referenced and used by Python. | +--------------------------------------------------+----------------------------------------------------------------------------+ -| :enum:`return_value_policy::reference_internal` | Reference the object, but do not take ownership. The object is considered | -| | be owned by the C++ instance whose method or property returned it. The | -| | Python object will increase the reference count of this 'parent' by 1 | -| | to ensure that it won't be deallocated while Python is using the 'child' | +| :enum:`return_value_policy::reference_internal` | This policy only applies to methods and properties. It references the | +| | object without taking ownership similar to the above | +| | :enum:`return_value_policy::reference` policy. In contrast to that policy, | +| | the function or property's implicit ``this`` argument (called the *parent*)| +| | is considered to be the the owner of the return value (the *child*). | +| | pybind11 then couples the lifetime of the parent to the child via a | +| | reference relationship that ensures that the parent cannot be garbage | +| | collected while Python is still using the child. More advanced variations | +| | of this scheme are also possible using combinations of | +| | :enum:`return_value_policy::reference` and the :class:`keep_alive` call | +| | policy described next. | +--------------------------------------------------+----------------------------------------------------------------------------+ -.. 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 above. - -.. note:: - - The next section on :ref:`call_policies` discusses *call policies* that can be - specified *in addition* to a return value policy from the list above. Call - policies indicate reference relationships that can involve both return values - and parameters of functions. - -.. note:: - - As an alternative to elaborate call policies and lifetime management logic, - consider using smart pointers (see :ref:`smart_pointers` for details) that - can be used to share reference count information between C++ and Python. - - -See below for an example that uses the +The following example snippet shows a use case of the :enum:`return_value_policy::reference_internal` policy. .. code-block:: cpp @@ -485,11 +471,34 @@ See below for an example that uses the py::class_(m, "Example") .def(py::init<>()) - .def("get_internal", &Example::get_internal, "Return the internal data", py::return_value_policy::reference_internal); + .def("get_internal", &Example::get_internal, "Return the internal data", + py::return_value_policy::reference_internal); 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. + +.. note:: + + The next section on :ref:`call_policies` discusses *call policies* that can be + specified *in addition* to a return value policy from the list above. Call + policies indicate reference relationships that can involve both return values + and parameters of functions. + +.. note:: + + As an alternative to elaborate call policies and lifetime management logic, + consider using smart pointers (see the section on :ref:`smart_pointers` for + details). Smart pointers can tell whether an object is still referenced from + C++ or Python, which generally eliminates the kinds of inconsistencies that + can lead to crashes or undefined behavior. For functions returning smart + pointers, it is not necessary to specify a return value policy. .. _call_policies: @@ -590,10 +599,10 @@ Smart pointers ============== This section explains how to pass values that are wrapped in "smart" pointer -types with internal reference counting. For simpler C++11 unique pointers, -please refer to the previous section. +types with internal reference counting. For the simpler C++11 unique pointers, +refer to the previous section. -The binding generator for classes (:class:`class_`) takes an optional second +The binding generator for classes, :class:`class_`, takes an optional second template type, which denotes a special *holder* type that is used to manage references to the object. When wrapping a type named ``Type``, the default value of this template parameter is ``std::unique_ptr``, which means that diff --git a/docs/basics.rst b/docs/basics.rst index 42ff6e42e..a2a608488 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -253,7 +253,9 @@ as arguments and return values, refer to the section on binding :ref:`classes`. +----------------------------+--------------------------+-----------------------+ | std::pair | Pair of two custom types | pybind11/pybind11.h | +----------------------------+--------------------------+-----------------------+ -| std::tuple<....> | Arbitrary tuple of types | pybind11/pybind11.h | +| std::tuple<...> | Arbitrary tuple of types | pybind11/pybind11.h | ++----------------------------+--------------------------+-----------------------+ +| std::reference_wrapper<...>| Reference type wrapper | pybind11/pybind11.h | +----------------------------+--------------------------+-----------------------+ | std::complex | Complex numbers | pybind11/complex.h | +----------------------------+--------------------------+-----------------------+ diff --git a/docs/changelog.rst b/docs/changelog.rst index 63806d8fd..46c85185d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -8,13 +8,13 @@ Changelog * Added a new ``move`` return value policy that triggers C++11 move semantics. The automatic return value policy falls back to this case when a rvalue reference is encountered +* Significantly more general GIL state routines that are used instead of + Python's troublesome ``PyGILState_Ensure`` and ``PyGILState_Release`` API * ``keep_alive`` fix: don't fail when there is no patient * ``functional.h``: acquire the GIL before calling Python function * Added Python RAII type wrappers ``none`` and ``iterable`` * Added ``*args`` and ``*kwargs`` pass-through parameters to ``pybind11.get_include()`` function -* Significantly more general GIL state routines that are used instead of - Python's troublesome ``PyGILState_Ensure`` and ``PyGILState_Release`` API. * Documentation improvements: ``opaque``, return value policies 1.5 (April 21, 2016) diff --git a/docs/conf.py b/docs/conf.py index a05acc33e..ca76e196e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -158,7 +158,7 @@ else: # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['.static'] +html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/faq.rst b/docs/faq.rst index 7e45b8c9a..255610597 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -144,7 +144,7 @@ the included test suite contains the following symbol: .. code-block:: cpp - __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_ + __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS​3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_ which is the mangled form of the following function type: diff --git a/include/pybind11/common.h b/include/pybind11/common.h index aba804f7b..8bfa77838 100644 --- a/include/pybind11/common.h +++ b/include/pybind11/common.h @@ -149,7 +149,7 @@ enum class return_value_policy : int { automatic = 0, /** As above, but use policy return_value_policy::reference when the return - value is a pointer. */ + value is a pointer. You probably won't need to use this. */ automatic_reference, /** Reference an existing object (i.e. do not create a new copy) and take @@ -172,14 +172,20 @@ enum class return_value_policy : int { /** Reference an existing object, but do not take ownership. The C++ side is responsible for managing the object’s lifetime and deallocating it when it is no longer used. Warning: undefined behavior will ensue when - the C++ side deletes an object that is still referenced by Python. */ + the C++ side deletes an object that is still referenced and used by + Python. */ reference, - /** Reference the object, but do not take ownership. The object is - considered be owned by the C++ instance whose method or property - returned it. The Python object will increase the reference count of this - ‘parent’ by 1 to ensure that it won’t be deallocated while Python is - using the ‘child’ */ + /** This policy only applies to methods and properties. It references the + object without taking ownership similar to the above + return_value_policy::reference policy. In contrast to that policy, the + function or property’s implicit this argument (called the parent) is + considered to be the the owner of the return value (the child). + pybind11 then couples the lifetime of the parent to the child via a + reference relationship that ensures that the parent cannot be garbage + collected while Python is still using the child. More advanced + variations of this scheme are also possible using combinations of + return_value_policy::reference and the keep_alive call policy */ reference_internal };