| =================================== |
| Boost.Python_ Internals |(logo)|__ |
| =================================== |
| |
| .. |(logo)| image:: ../../../boost.png |
| :alt: Boost |
| :class: boost-logo |
| |
| __ ../../../index.htm |
| |
| .. _`Boost.Python`: index.html |
| |
| .. _license: ../../../LICENSE_1_0.txt |
| |
| |
| ------------------------------------------------------- |
| A conversation between Brett Calcott and David Abrahams |
| ------------------------------------------------------- |
| |
| :copyright: Copyright David Abrahams and Brett Calcott 2003. See |
| accompanying license_ for terms of use. |
| |
| In both of these cases, I'm quite capable of reading code - but the |
| thing I don't get from scanning the source is a sense of the |
| architecture, both structurally, and temporally (er, I mean in what |
| order things go on). |
| |
| 1) What happens when you do the following:: |
| |
| struct boring {}; |
| ...etc... |
| class_<boring>("boring") |
| ; |
| |
| There seems to be a fair bit going on. |
| |
| - Python needs a new ClassType to be registered. |
| - We need to construct a new type that can hold our boring struct. |
| - Inward and outward converters need to be registered for the type. |
| |
| Can you gesture in the general direction where these things are done? |
| |
| I only have time for a "off-the-top-of-my-head" answer at the moment; |
| I suggest you step through the code with a debugger after reading this |
| to see how it works, fill in details, and make sure I didn't forget |
| anything. |
| |
| A new (Python) subclass of Boost.Python.Instance (see |
| libs/python/src/object/class.cpp) is created by invoking |
| Boost.Python.class, the metatype:: |
| |
| >>> boring = Boost.Python.class( |
| ... 'boring' |
| ... , bases_tuple # in this case, just () |
| ... , { |
| ... '__module__' : module_name |
| ... , '__doc__' : doc_string # optional |
| ... } |
| ... ) |
| |
| A handle to this object is stuck in the m_class_object field |
| of the registration associated with ``typeid(boring)``. The |
| registry will keep that object alive forever, even if you |
| wipe out the 'boring' attribute of the extension module |
| (probably not a good thing). |
| |
| Because you didn't specify ``class<boring, non_copyable, |
| ...>``, a to-python converter for boring is registered which |
| copies its argument into a value_holder held by the the |
| Python boring object. |
| |
| Because you didn't specify ``class<boring ...>(no_init)``, |
| an ``__init__`` function object is added to the class |
| dictionary which default-constructs a boring in a |
| value_holder (because you didn't specify some smart pointer |
| or derived wrapper class as a holder) held by the Python |
| boring object. |
| |
| ``register_class_from_python`` is used to register a |
| from-python converter for ``shared_ptr<boring>``. |
| ``boost::shared_ptr``\ s are special among smart pointers |
| because their Deleter argument can be made to manage the |
| whole Python object, not just the C++ object it contains, no |
| matter how the C++ object is held. |
| |
| If there were any ``bases<>``, we'd also be registering the |
| relationship between these base classes and boring in the |
| up/down cast graph (``inheritance.[hpp/cpp]``). |
| |
| In earlier versions of the code, we'd be registering lvalue |
| from-python converters for the class here, but now |
| from-python conversion for wrapped classes is handled as a |
| special case, before consulting the registry, if the source |
| Python object's metaclass is the Boost.Python metaclass. |
| |
| Hmm, that from-python converter probably ought to be handled |
| the way class converters are, with no explicit conversions |
| registered. |
| |
| 2) Can you give a brief overview of the data structures that are |
| present in the registry |
| |
| The registry is simple: it's just a map from typeid -> |
| registration (see boost/python/converter/registrations.hpp). |
| ``lvalue_chain`` and ``rvalue_chain`` are simple endogenous |
| linked lists. |
| |
| If you want to know more, just ask. |
| |
| If you want to know about the cast graph, ask me something specific in |
| a separate message. |
| |
| and an overview of the process that happens as a type makes its |
| way from c++ to python and back again. |
| |
| Big subject. I suggest some background reading: look for relevant |
| info in the LLNL progress reports and the messages they link to. |
| Also, |
| |
| http://mail.python.org/pipermail/c++-sig/2002-May/001023.html |
| |
| http://mail.python.org/pipermail/c++-sig/2002-December/003115.html |
| |
| http://aspn.activestate.com/ASPN/Mail/Message/1280898 |
| |
| http://mail.python.org/pipermail/c++-sig/2002-July/001755.html |
| |
| from c++ to python: |
| |
| It depends on the type and the call policies in use or, for |
| ``call<>(...)``, ``call_method<>(...)``, or ``object(...)``, if |
| ``ref`` or ``ptr`` is used. There are also two basic |
| categories to to-python conversion, "return value" conversion |
| (for Python->C++ calls) and "argument" conversion (for |
| C++->Python calls and explicit ``object()`` conversions). The |
| behavior of these two categories differs subtly in various ways |
| whose details I forget at the moment. You can probably find |
| the answers in the above references, and certainly in the code. |
| |
| The "default" case is by-value (copying) conversion, which uses |
| to_python_value as a to-python converter. |
| |
| Since there can sensibly be only one way to convert any type |
| to python (disregarding the idea of scoped registries for the |
| moment), it makes sense that to-python conversions can be |
| handled by specializing a template. If the type is one of |
| the types handled by a built-in conversion |
| (builtin_converters.hpp), the corresponding template |
| specialization of to_python_value gets used. |
| |
| Otherwise, to_python_value uses the ``m_to_python`` |
| function in the registration for the C++ type. |
| |
| Other conversions, like by-reference conversions, are only |
| available for wrapped classes, and are requested explicitly by |
| using ``ref(...)``, ``ptr(...)``, or by specifying different |
| CallPolicies for a call, which can cause a different to-python |
| converter to be used. These conversions are never registered |
| anywhere, though they do need to use the registration to find |
| the Python class corresponding to the C++ type being referred |
| to. They just build a new Python instance and stick the |
| appropriate Holder instance in it. |
| |
| |
| from python to C++: |
| |
| Once again I think there is a distinction between "return value" |
| and "argument" conversions, and I forget exactly what that is. |
| |
| What happens depends on whether an lvalue conversion is needed |
| (see http://mail.python.org/pipermail/c++-sig/2002-May/001023.html) |
| All lvalue conversions are also registered in a type's rvalue |
| conversion chain, since when an rvalue will do, an lvalue is |
| certainly good enough. |
| |
| An lvalue conversion can be done in one step (just get me the |
| pointer to the object - it can be ``NULL`` if no conversion is |
| possible) while an rvalue conversion requires two steps to |
| support wrapped function overloading and multiple converters for |
| a given C++ target type: first tell me if a conversion is |
| possible, then construct the converted object as a second step. |
| |