XS-MLVP
/
swig
mirror of https://github.com/swig/swig
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add docs on the python runtime module

This commit is contained in:
William S Fulton 2025-05-13 08:40:45 +01:00
parent 53453d51ec
commit 831fc60691
1 changed files with 50 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Doc/Manual/Python.html
View File

@ -1000,6 +1000,10 @@ module name, make sure you don't use the same name as a built-in
Python command or standard module name.
</p>
<p>
There is also a further 'behind the scenes' Python runtime module, but this implementation detail is covered later.
</p>
<H3><a name="Python_nn15">33.3.2 Functions</a></H3>
@ -2704,6 +2708,52 @@ in the file <tt>python/pyopers.swg</tt> in the SWIG library.
</p>
<H3><a name="Python_runtime_module">33.4.3 Python runtime module</a></H3>
<p>
In addition to the two Python modules that are generated by SWIG, there is also a third 'behind the scenes' Python runtime module.
The runtime module is very much an implementation level detail, but is mentioned here for completeness and for the inquisitive!
</p>
<p>
SWIG implements a run-time type checker for checking a Python type/class as it passes between the Python and C/C++ layers.
It is also used when multiple SWIG modules need to share type information with each other (when using the <tt>%import</tt> directive).
More details can be found in the <a href="Modules.html#Modules_nn2">SWIG runtime code</a> and <a href="Typemaps.html#Typemaps_runtime_type_checker">run-time type checker</a> sections.
The runtime module contains the following:
</p>
<ol>
<li> A <a href="https://docs.python.org/3/c-api/capsule.html">Python Capsule</a> containing a pointer to the underlying C module data structure used by the runtime type checker. For multiple modules to access the common runtime implementation. The Capsule is named <tt>type_pointer_capsule</tt> except when using <tt>-builtin</tt> when it is instead called <tt>type_pointer_capsule_builtin</tt>.</li>
<li> The builtin type <tt>SwigPyObject</tt> - Swig object holding a C/C++ pointer. For 'normal' pointers, that is, not for function pointers nor member function pointers.</li>
<li> The builtin type <tt>SwigPyPacked</tt> - Swig object holding a C/C++ function pointer. For C pointers to a function or C++ member function pointers.</li>
<li> The builtin type <tt>SwigVarLink</tt> - Swig variable link object. The type used by the 'cvar' field for accessing C/C++ global variables.</li>
</ol>
<p>
If multiple SWIG modules are being used, the C/C++ wrapped proxy classes/types can be shared or used across the different modules via the SWIG runtime.
The runtime is accessed and shared via the Capsule in the runtime module.
The Python runtime module is implemented as a Python builtin module. While users are unlikely to use or import the runtime module directly, it can be inspected simply enough.
The name of the module is <tt>swig_runtime_data</tt> appended with the runtime version as defined by <tt>SWIG_RUNTIME_VERSION</tt>.
First import your SWIG generated module. Next find the exact runtime module name so you know what to import before inspecting it with say <tt>dir</tt>.
The interpreter session below demonstrates this with a SWIG generated module called <tt>example</tt>:
</p>
<div class="targetlang">
<pre>
&gt;&gt;&gt; import example
&gt;&gt;&gt; import sys
&gt;&gt;&gt; list(m for m in sys.modules if m.startswith("swig_runtime_data"))
['swig_runtime_data5']
&gt;&gt;&gt; import swig_runtime_data5
&gt;&gt;&gt; dir(swig_runtime_data5)
['SwigPyObject', 'SwigPyPacked', 'SwigVarLink', '__doc__', '__loader__', '__name__', '__package__', '__spec__', 'type_pointer_capsule']
</pre>
</div>
<p>
<b>Compatibility Note:</b> Only the Capsule was stored in the Python runtime module prior to SWIG-4.4.0.
</p>
<H3><a name="Python_nn30">33.4.3 Memory management</a></H3>