[chimera-dev] Object lifetimes

[Thomas Goddard]

Here are some notes about how Chimera makes sure C++ and Python objects
are not prematurely deleted.  The current mechanism is fragile.

    Tom



Object lifetime problems
------------------------

Chimera's current mechanism for knowing when to delete C++ and Python
objects has problems.  Here's the basic example

	atom.color = MaterialColor(red, green, blue)

This code results in the C++ Atom object saving a pointer to the
C++ MaterialColor object.  The trouble is that the Python MaterialColor
object needs to be referenced so it does not get deleted.  If the
Python MaterialColor gets deleted then it will delete the C++ color
and the Atom will hold a bad pointer, the program will crash.

  The way this is currently handled is that object attributes wrapped by
WrapPy have a reference to the most recently set value.  So the Python
atom object above will have a atom.__cached_color attribute.  The trouble
with this solution is that object attributes do not exist for all the
C++ pointers saved by the C++ objects.  For example,

    openModels.add([Molecule()])

This causes the C++ OpenModels object to save a pointer to the C++
Molecule.  But what keeps the Python Molecule from being deleted?  The
OpenModels object has no attributes giving the models, and even if it
did the WrapPy cached value would not be updated by the above call.  I
don't know what reference keeps the Python Molecule from being
deleted.  Maybe Greg know.  If the Python molecule is deleted it will
delete the C++ molecule and OpenModels will hold a bad pointer.

  The core of the problem is that there is no bookkeeping of pointer
references in C++.  The current WrapPy mechanism is just a bandaid
that makes the system work but it is very fragile and error prone.
Also caching all the attribute values may be why creating Python atoms
and bonds is so slow.  Also one has to be careful to not make attributes
that do large computations.  That is unexpected behaviour.

  I don't think there is any simple fix.  Making the C++ code include
pointer book-keeping code is a big burden on the C++.  Making wrapped
C++ objects objects hold a reference to the Python object is another
solution (Sparky does this).  So the Python object can never be deleted
unless you call a special C++ function, like molecule.destroy().
This is a burden to the Python programmer, and is unexpected behaviour
in Python.