[C++-sig] Re: register_ptr_to_python docs and test

[David Abrahams]

Nicodemus <nicodemus at globalite.com.br> writes:

> David Abrahams wrote:
>
>>Nicodemus <nicodemus at globalite.com.br> writes:
>>
>>  
>>><h2>Introduction</h2>
>>>
>>>  <code><boost/python/converter/register_ptr_to_python.hpp></code>
>>>    
>>          ^                                                 ^
>>          &lt;                                              &gt;
>>
>>You have this problem throughout.  Did you validate your html?
>>  
>
> No, I didn't, sorry. But I tested it in mozilla and internet explorer,
> and both display it fine. But even checking the text for this kind of
> error, I couldn't find any, even this one you're pointing. I guess the
> html got mixed up in the sending? It happened before in another doc
> patch... 8/

Actually it was just GNUs helpfully "Washing" the embedded HTML in
display.  The article came through just fine, sorry.

>>>  defines a function that allows the user to register smart
>>>  pointers for classes with virtual member functions that will be
>>>  overwritten in Python.
>>>    
>>
>>You mean "overridden" and not "overwritten".
>
> Sure! Sorry.
>
>>  But this has nothing at all to do with virtual member functions
>>  AFAICT.
>>
>
> Yeah, it is because of how the C++ object is held in Python, because
> of the wrapper class; but you are right, this paragraph does not
> explain it well.
>
>>  <code>&lt;boost/python/converter/register_ptr_to_python.hpp&gt;</code>
>>  supplies <code>register_ptr_to_python</code>, a function template
>>  which registers a conversion from a smart pointers to Python.  The
>>  resulting Python object holds a copy of the converted smart pointer,
>>  but behaves as though it were a wrapped copy of the pointee.  If
>>  the pointee type has virtual functions and the class representing
>>  its dynamic (most-derived) type has been wrapped, the Python object
>>  will be an instance of the wrapper for the most-derived type.
>>  
>
> WAY better!

Thanks ;-)

>>>  Classes that have virtual methods (and the user has supplied a
>>>  wrapper, <code>X_Wrapper</code>, allowing Python to callback into
>>>  C++) live in Python not as <code>X</code> objects, but as
>>>  instances of the wrapper class.  This is a problem because
>>>  conversions to-python of <code>smart_ptr<X></code> objects won't
>>>  work since the objects that live in Python are held actually by
>>>  <code>smart_ptr<X_Wrapper></code> instances.
>>>    
>>
>>OK, this is one reason you might want to do use
>>register_ptr_to_python, but it's not the only reason.
>
> Sorry, that was the only reason I knew... what's the other?

If you want to enable any kind of smart pointer to be converted to
Python, this is how you register the converter.  You can only cause
one kind of smart pointer to be registered as a consequence of using
it in the class_<...> parameters.  This lets you register as many as
you want.  Using a variety of smart pointers you can create all kinds
of smart proxies.  For example, Joel is just finishing work on a
system for wrapping indexed containers which uses a kind of smart
pointer which keeps the container alive and contains the index to
use, and does range checking on dereference.

>>>  Using the function in this header to register the smart pointer
>>> allows correct conversion to-python of <code>smart_ptr<X></code>
>>> instances, but has one drawback: a <code>X</code> object created
>>> in Python will not be able to be passed as a
>>> <code>smart_ptr<X>&amp;</code> argument.  But it is still possible
>>> to pass a X object created in Python as <code>smart_ptr<X></code>,
>>> <code>smart_ptr<X_Wrapper></code>, <code>smart_ptr<X>
>>> const&amp;</code>, or <code>smart_ptr<X_Wrapper> const&amp;</code>
>>> as an argument.
>>>    
>>
>>That's because, unless X is wrapped with smart_ptr<X> as a template
>>argument to its class_<...>, X objects created in Python are held
>>directly in the containing Python object.
>>  
>
> Using register_ptr_to_python to register the smart pointer
> allows correct to-python conversions of smart_ptr
> instances, but has one drawback: a X object created in Python
> will not be able to be passed as a smart_ptr<X> &
> argument because, unless X is wrapped with smart_ptr<X> as
> a template argument to its class_<...>, X objects created in Python are
> held directly in the containing Python object. 
> But it is still possible to pass a X object created in Python as
> smart_ptr<X>, smart_ptr<X_Wrapper>, smart_ptr<X> const&, or
> smart_ptr<X_Wrapper> const& as an argument to a function.

I'd rather not phrase this as a drawback of using this function,
because it's really not.  It *is* useful to note that in order to
convert a Python X object to a smart_ptr<X>& (non-const reference
other than shared_ptr<X>&), the embedded C++ object must be held by
smart_ptr<X>, and that when wrapped objects are created by calling the
constructor from Python, how they are held is determined by the
HeldType parameter to class_<...>

> ?
>
>>>Here is an example of a module that contains a class <code>A</code> with
>>>virtual methods and some functions that work with
>>>    
>>          ^^^^^^^
>>functions.
>>
>
> Fixed.
>
> Dave, we can discuss changes here and then I can commit myself, if you want.

That sounds great.  I think we're almost there.  Thanks for your work!

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com