1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6<meta name="generator" content="Docutils 0.3.0: http://docutils.sourceforge.net/" /> 7<title>Boost.Python Internals Boost</title> 8<link rel="stylesheet" href="../../../rst.css" type="text/css" /> 9</head> 10<body> 11<div class="document" id="boost-python-internals-logo"> 12<h1 class="title"><a class="reference" href="index.html">Boost.Python</a> Internals <a class="reference" href="../../../index.htm"><img alt="Boost" src="../../../boost.png" /></a></h1> 13<div class="section" id="a-conversation-between-brett-calcott-and-david-abrahams"> 14<h1><a name="a-conversation-between-brett-calcott-and-david-abrahams">A conversation between Brett Calcott and David Abrahams</a></h1> 15<table class="field-list" frame="void" rules="none"> 16<col class="field-name" /> 17<col class="field-body" /> 18<tbody valign="top"> 19<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright David Abrahams and Brett Calcott 2003. See 20accompanying <a class="reference" href="../../../LICENSE_1_0.txt">license</a> for terms of use.</td> 21</tr> 22</tbody> 23</table> 24<p>In both of these cases, I'm quite capable of reading code - but the 25thing I don't get from scanning the source is a sense of the 26architecture, both structurally, and temporally (er, I mean in what 27order things go on).</p> 28<ol class="arabic"> 29<li><p class="first">What happens when you do the following:</p> 30<pre class="literal-block"> 31struct boring {}; 32...etc... 33class_<boring>("boring") 34 ; 35</pre> 36</li> 37</ol> 38<p>There seems to be a fair bit going on.</p> 39<blockquote> 40<ul class="simple"> 41<li>Python needs a new ClassType to be registered.</li> 42<li>We need to construct a new type that can hold our boring struct.</li> 43<li>Inward and outward converters need to be registered for the type.</li> 44</ul> 45</blockquote> 46<p>Can you gesture in the general direction where these things are done?</p> 47<blockquote> 48<p>I only have time for a "off-the-top-of-my-head" answer at the moment; 49I suggest you step through the code with a debugger after reading this 50to see how it works, fill in details, and make sure I didn't forget 51anything.</p> 52<blockquote> 53<p>A new (Python) subclass of Boost.Python.Instance (see 54libs/python/src/object/class.cpp) is created by invoking 55Boost.Python.class, the metatype:</p> 56<pre class="literal-block"> 57>>> boring = Boost.Python.class( 58... 'boring' 59... , bases_tuple # in this case, just () 60... , { 61... '__module__' : module_name 62... , '__doc__' : doc_string # optional 63... } 64... ) 65</pre> 66<p>A handle to this object is stuck in the m_class_object field 67of the registration associated with <tt class="literal"><span class="pre">typeid(boring)</span></tt>. The 68registry will keep that object alive forever, even if you 69wipe out the 'boring' attribute of the extension module 70(probably not a good thing).</p> 71<p>Because you didn't specify <tt class="literal"><span class="pre">class<boring,</span> <span class="pre">non_copyable,</span> 72<span class="pre">...></span></tt>, a to-python converter for boring is registered which 73copies its argument into a value_holder held by the the 74Python boring object.</p> 75<p>Because you didn't specify <tt class="literal"><span class="pre">class<boring</span> <span class="pre">...>(no_init)</span></tt>, 76an <tt class="literal"><span class="pre">__init__</span></tt> function object is added to the class 77dictionary which default-constructs a boring in a 78value_holder (because you didn't specify some smart pointer 79or derived wrapper class as a holder) held by the Python 80boring object.</p> 81<p><tt class="literal"><span class="pre">register_class_from_python</span></tt> is used to register a 82from-python converter for <tt class="literal"><span class="pre">shared_ptr<boring></span></tt>. 83<tt class="literal"><span class="pre">boost::shared_ptr</span></tt>s are special among smart pointers 84because their Deleter argument can be made to manage the 85whole Python object, not just the C++ object it contains, no 86matter how the C++ object is held.</p> 87<p>If there were any <tt class="literal"><span class="pre">bases<></span></tt>, we'd also be registering the 88relationship between these base classes and boring in the 89up/down cast graph (<tt class="literal"><span class="pre">inheritance.[hpp/cpp]</span></tt>).</p> 90<p>In earlier versions of the code, we'd be registering lvalue 91from-python converters for the class here, but now 92from-python conversion for wrapped classes is handled as a 93special case, before consulting the registry, if the source 94Python object's metaclass is the Boost.Python metaclass.</p> 95<p>Hmm, that from-python converter probably ought to be handled 96the way class converters are, with no explicit conversions 97registered.</p> 98</blockquote> 99</blockquote> 100<ol class="arabic" start="2"> 101<li><p class="first">Can you give a brief overview of the data structures that are 102present in the registry</p> 103<blockquote> 104<p>The registry is simple: it's just a map from typeid -> 105registration (see boost/python/converter/registrations.hpp). 106<tt class="literal"><span class="pre">lvalue_chain</span></tt> and <tt class="literal"><span class="pre">rvalue_chain</span></tt> are simple endogenous 107linked lists.</p> 108<p>If you want to know more, just ask.</p> 109<p>If you want to know about the cast graph, ask me something specific in 110a separate message.</p> 111</blockquote> 112<p>and an overview of the process that happens as a type makes its 113way from c++ to python and back again.</p> 114</li> 115</ol> 116<blockquote> 117<p>Big subject. I suggest some background reading: look for relevant 118info in the LLNL progress reports and the messages they link to. 119Also,</p> 120<blockquote> 121<p><a class="reference" href="http://mail.python.org/pipermail/c++-sig/2002-May/001023.html">http://mail.python.org/pipermail/c++-sig/2002-May/001023.html</a></p> 122<p><a class="reference" href="http://mail.python.org/pipermail/c++-sig/2002-December/003115.html">http://mail.python.org/pipermail/c++-sig/2002-December/003115.html</a></p> 123<p><a class="reference" href="http://aspn.activestate.com/ASPN/Mail/Message/1280898">http://aspn.activestate.com/ASPN/Mail/Message/1280898</a></p> 124<p><a class="reference" href="http://mail.python.org/pipermail/c++-sig/2002-July/001755.html">http://mail.python.org/pipermail/c++-sig/2002-July/001755.html</a></p> 125</blockquote> 126<p>from c++ to python:</p> 127<blockquote> 128<p>It depends on the type and the call policies in use or, for 129<tt class="literal"><span class="pre">call<>(...)</span></tt>, <tt class="literal"><span class="pre">call_method<>(...)</span></tt>, or <tt class="literal"><span class="pre">object(...)</span></tt>, if 130<tt class="literal"><span class="pre">ref</span></tt> or <tt class="literal"><span class="pre">ptr</span></tt> is used. There are also two basic 131categories to to-python conversion, "return value" conversion 132(for Python->C++ calls) and "argument" conversion (for 133C++->Python calls and explicit <tt class="literal"><span class="pre">object()</span></tt> conversions). The 134behavior of these two categories differs subtly in various ways 135whose details I forget at the moment. You can probably find 136the answers in the above references, and certainly in the code.</p> 137<p>The "default" case is by-value (copying) conversion, which uses 138to_python_value as a to-python converter.</p> 139<blockquote> 140<p>Since there can sensibly be only one way to convert any type 141to python (disregarding the idea of scoped registries for the 142moment), it makes sense that to-python conversions can be 143handled by specializing a template. If the type is one of 144the types handled by a built-in conversion 145(builtin_converters.hpp), the corresponding template 146specialization of to_python_value gets used.</p> 147<p>Otherwise, to_python_value uses the <tt class="literal"><span class="pre">m_to_python</span></tt> 148function in the registration for the C++ type.</p> 149</blockquote> 150<p>Other conversions, like by-reference conversions, are only 151available for wrapped classes, and are requested explicitly by 152using <tt class="literal"><span class="pre">ref(...)</span></tt>, <tt class="literal"><span class="pre">ptr(...)</span></tt>, or by specifying different 153CallPolicies for a call, which can cause a different to-python 154converter to be used. These conversions are never registered 155anywhere, though they do need to use the registration to find 156the Python class corresponding to the C++ type being referred 157to. They just build a new Python instance and stick the 158appropriate Holder instance in it.</p> 159</blockquote> 160<p>from python to C++:</p> 161<blockquote> 162<p>Once again I think there is a distinction between "return value" 163and "argument" conversions, and I forget exactly what that is.</p> 164<p>What happens depends on whether an lvalue conversion is needed 165(see <a class="reference" href="http://mail.python.org/pipermail/c++-sig/2002-May/001023.html">http://mail.python.org/pipermail/c++-sig/2002-May/001023.html</a>) 166All lvalue conversions are also registered in a type's rvalue 167conversion chain, since when an rvalue will do, an lvalue is 168certainly good enough.</p> 169<p>An lvalue conversion can be done in one step (just get me the 170pointer to the object - it can be <tt class="literal"><span class="pre">NULL</span></tt> if no conversion is 171possible) while an rvalue conversion requires two steps to 172support wrapped function overloading and multiple converters for 173a given C++ target type: first tell me if a conversion is 174possible, then construct the converted object as a second step.</p> 175</blockquote> 176</blockquote> 177</div> 178</div> 179<hr class="footer"/> 180<div class="footer"> 181<a class="reference" href="internals.rst">View document source</a>. 182Generated on: 2003-09-12 14:51 UTC. 183Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. 184</div> 185</body> 186</html> 187
