[Zodb-checkins] CVS: Packages/StorageGC - CyclicGC.py:1.4

[tim@digicool.com]

Update of /cvs-repository/Packages/StorageGC
In directory korak:/tmp/cvs-serv31116/storagegc

Modified Files:
	CyclicGC.py 
Log Message:
Doc clarification:  *All* the functions in the GCable interface have to
be prepared to deal gracefully with oids that no longer exist.  But
there's an alternative to that, explained in a new paragraph.
Not mentioned in the user-level docs is that CycleGC also has to deal
gracefully with that the list of oids returned from .gcReferences(x) for
a fixed x may change across calls.



--- Updated File CyclicGC.py in package Packages/StorageGC --
--- CyclicGC.py	2001/04/19 19:15:29	1.3
+++ CyclicGC.py	2001/04/20 06:41:05	1.4
@@ -18,18 +18,32 @@
 #     of y's refcounts; if x accounts for N of y's refcounts, then y must
 #     appear exactly N times in gcReferences(x).
 #
-# GCable.trash(oids) -> None
+# GCable.gcTrash(oids) -> None
 #     This is a callback, invoked when CycleGC has discovered cyclic
 #     garbage.  oids is a list of objects in garbage cycles, and of objects
 #     reachable only from garbage cycles.
-#     trash() must be robust in the face of an oid that no longer exists,
-#     since CycleGC can run incrementally, and oids it was originally told
-#     about may no longer exist by the time it discovers they were trash.
 
+# CAUTION:  All the GCable functions must be robust in the face of an oid
+# that no longer exists, since CycleGC can run incrementally, and oids that
+# existed at the time of the CycleGC.start() call may no longer exist at
+# the time(s) CycleGC asks the storage for info about them.  "Robust"
+# means they must not raise an exception when passed an oid that no longer
+# exists.  It's suggested, but not required, that .trash() ignore a non-
+# existent oid, .gcRefcount() return 0, and .gcReferences() an empty list.
+# XXX We're skating on thin ice here, under the assumption that CycleGC
+# XXX *can* be made safe despite never being told about any topology
+# XXX changes.  It remains unclear whether that's actually possible.
+#
+# Alternatively, the storage could refrain from acting on .gcTrash()
+# callbacks (just queuing up the intermediate results) until CycleGC.done()
+# is true.  That is, if the storage doesn't destroy anything before
+# CycleGC is finished, then of course CycleGC won't ask the storage about
+# oids that don't exist anymore.
+
 ###########################################################################
 # The CycleGC interface.
 # The CycleGC class here supplies the following methods for use by
-# refcounted storages desiring detecting of unreachabe cycles.
+# refcounted storages desiring detecting of unreachable cycles.
 #
 # Typical use:
 #