[ZODB-Dev] proposed comments

[Florent Guillaume]

Is it ok if I add the following comments to Connection's docstring?  
Are there inaccuracies?

     - _cache is a PickeCache, a cache which can ghostify objects not
       recently used. Its API is roughly that of a dict, with additional
       gc-related and invalidation-related methods.

     - _added is a dict of oid->obj added explicitely through add().
       _added is used as a sort of preliminary cache until commit time
       where objects are all moved to the real _cache. The object are
       moved to _creating at commit time.

     - _registered_objects is the list of objects registered by
       Persistence when the object was first changed, or by add(). It
       also contains objects who ended up in a ReadConflictError,  
just to
       be able to clean them up from the cache on abort with the other
       modified objects. All objects of this list are either in  
_cache or
       in _added.

     During commit, all these objects go to either _modified or  
_creating:

     - _creating is a dict of oid->flag of new objects (without serial),
       either added by add() or implicitely added (discovered by the
       serializer during commit). The flag is True for implicit adding.
       _creating is used during abort to remove created objects from the
       _cache, and by persistent_id to check that a new object isn't
       reachable from multiple databases.

     - _modified is a list of oids modified, which have to be  
invalidated
       in the cache on abort and in other connections on finish.

Florent

-- 
Florent Guillaume, Nuxeo (Paris, France)   Director of R&D
+33 1 40 33 71 59   http://nuxeo.com   fg at nuxeo.com