123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182 |
- ===================================
- 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.
|