[Kde-bindings] Smoke call policy question

[Ashley Winters]

--- Roberto Alsina <ralsina at kde.org> wrote:
>    
> A little over a year after I first looked at Smoke, I am looking
> again, this 
> time using Boost::Python and Pyste, and... of course I am not geting
> it ;-)
> 
> Specifically, what's the ownership semantics of calling stuff in
> smokelib?
> 
> If I call SmokeBinding::className() who owns the char *?

If I recall, nobody is permitted to delete it. Once it's returned, it's
effectively global. You could try to clean it up, but it's better to
make the className() return a hash value.

> If I call Smoke::cast() who owns the returned object?

It's not returning a new object, so the ownership doesn't change that
way.

> It would be specially useful if it could be explained in terms used
> by Boost:
> 
>
http://www.boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.call_policies

I don't know if I can put it in that context, but I can lay out the
ground-rules.

Smoke can only deal with composite (class/struct) objects as pointers.
It's your responsibility to pass pointers into the Smoke functions you
call, even if they take a bare object. Smoke automatically dereferences
the pointer and passes the object to your function.

When Smoke has to return a bare object by value (say, a QRect), it will
return a new QRect(rect), and pass ownership to you.

How is ownership tracked by other bindings? It's very devious, and is
handled with the "Marshall" classes, which are part of the Smoke
client-side utilities, but not the Smoke library itself. Therefore, you
don't necessarily have to use this mechanism for your binding, since
it's not inherent to the Smoke library.

Each type of conversion between C++ object and Language object has its
own subclass of Marshall (see marshall.h for the base class).

from PerlQt, and likely extended further by Korundum & friends:
* MethodCall
* MethodReturnValue
* VirtualMethodCall
* VirtualMethodReturnValue
* EmitSignal
* InvokeSlot

Each of those subclasses encodes a certain set of rules for ownership
by overriding the cleanup() pure virtual method, and a few other
things.

The various conversion functions (marshall_QSomeThing) take a Marshall*
object, and check whether ->cleanup() is true, and also whether the
object they're converting isStack(), rather than isPtr(). If so, they
perform whatever copy or deletion is necessary for that object to be
cleaned up. Sometimes, the object is going to be deleted by Smoke, and
you'll need to copy it into the Language's context. Sometimes Smoke
created a new copy in order to return it, and *you* need to take
responsibility for deleting it. Both conditions are signaled with
m->cleanup(), and which one depends on the context.

Just keep in mind, that as a general rule, Smoke deletes anything it
independently creates, as soon as it gets control back from you.
However, it has no way to delete objects returned by value -- that's
your responsibility.

- Ashley Winters


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com