diff options
Diffstat (limited to 'sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst')
| -rw-r--r-- | sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst b/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst index ff6ea5317..12b866ad7 100644 --- a/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst +++ b/sources/shiboken2/ApiExtractor/doc/typesystem_manipulating_objects.rst @@ -11,6 +11,9 @@ inject-code given type or function, and it is a child of the :ref:`object-type`, :ref:`value-type`, :ref:`modify-function` and :ref:`add-function` nodes. + The code can be embedded into XML (be careful to use the correct XML entities + for characters like '<', '>', '&'): + .. code-block:: xml <value-type> @@ -20,6 +23,18 @@ inject-code </inject-code> </value-type> + or obtained from an external file: + + .. code-block:: xml + + <value-type> + <inject-code class="native | target | target-declaration" + position="beginning | end" since="..." + file="external_source.cpp" + snippet="label"/> + </value-type> + + The ``class`` attribute specifies which module of the generated code that will be affected by the code injection. The ``class`` attribute accepts the following values: @@ -28,6 +43,8 @@ inject-code * target: The binding code * target-declaration: The code will be injected into the generated header file containing the c++ wrapper class definition. + * file: The file name + * snippet: The snippet label (optional) If the ``position`` attribute is set to *beginning* (the default), the code is inserted at the beginning of the function. If it is set to *end*, the code @@ -35,6 +52,16 @@ inject-code The ``since`` attribute specify the API version where this code was injected. + If a ``snippet`` label is given, the code between annotations of the form + + .. code-block:: c++ + + // @snippet label + ... + // @snippet label + + will be extracted. + modify-field ^^^^^^^^^^^^ @@ -74,6 +101,8 @@ modify-function since="..." remove="all | c++" access="public | private | protected" + allow-thread="true | auto | false" + exception-handling="off | auto-off | auto-on | on" rename="..." /> </object-type> @@ -82,6 +111,26 @@ modify-function The ``since`` attribute specify the API version when this function was modified. + The ``allow-thread`` attribute specifies whether a function should be wrapped + into ``Py_BEGIN_ALLOW_THREADS`` and ``Py_END_ALLOW_THREADS``, that is, + temporarily release the GIL (global interpreter lock). Doing so is required + for any thread-related function (wait operations), functions that might call + a virtual function (potentially reimplemented in Python), and recommended for + lengthy I/O operations or similar. It has performance costs, though. + The value ``auto`` means that it will be turned off for functions for which + it is deemed to be safe, for example, simple getters. + + The ``exception-handling`` attribute specifies whether to generate exception + handling code (nest the function call into try / catch statements). It accepts + the following values: + + * no, false: Do not generate exception handling code + * auto-off: Generate exception handling code for functions + declaring a non-empty ``throw`` list + * auto-on: Generate exception handling code unless function + declares ``noexcept`` + * yes, true: Always generate exception handling code + The ``remove``, ``access`` and ``rename`` attributes are *optional* attributes for added convenience; they serve the same purpose as the deprecated tags :ref:`remove`, :ref:`access` and :ref:`rename`. @@ -130,3 +179,4 @@ conversion-rule .. note:: You can also use the conversion-rule node to specify :ref:`how the conversion of a single function argument should be done in a function <conversion-rule>`. + The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes). |