[Zope-CVS] CVS: Products/Ape/lib/apelib/zodb3 - connection.py:1.6.2.5 scanner.py:1.2.2.3

Shane Hathaway shane at zope.com
Sat Jan 3 00:42:46 EST 2004


Update of /cvs-repository/Products/Ape/lib/apelib/zodb3
In directory cvs.zope.org:/tmp/cvs-serv12099

Modified Files:
      Tag: ape-0_8-branch
	connection.py scanner.py 
Log Message:
Added docstrings to scanner.py


=== Products/Ape/lib/apelib/zodb3/connection.py 1.6.2.4 => 1.6.2.5 ===
--- Products/Ape/lib/apelib/zodb3/connection.py:1.6.2.4	Sat Dec 20 23:24:06 2003
+++ Products/Ape/lib/apelib/zodb3/connection.py	Sat Jan  3 00:42:44 2004
@@ -60,7 +60,8 @@
             ctl = self._scan_ctl
             if ctl is None:
                 self._scan_ctl = ctl = odb._scan_ctl.newConnection()
-            if ctl.ready():
+            if ctl.elapsed():
+                # Scan, letting the scanner know which OIDs still matter.
                 ctl.setOIDs(self._cache.cache_data.keys())
                 # If there were any invalidations, process them now.
                 if self._invalidated:


=== Products/Ape/lib/apelib/zodb3/scanner.py 1.2.2.2 => 1.2.2.3 ===
--- Products/Ape/lib/apelib/zodb3/scanner.py:1.2.2.2	Sat Dec 20 02:31:08 2003
+++ Products/Ape/lib/apelib/zodb3/scanner.py	Sat Jan  3 00:42:44 2004
@@ -31,6 +31,16 @@
 
 
 class ScanControl:
+    """Scanning for a pool of connections.
+
+    A ScanControl instance is an attribute of an ApeDB instance.  The
+    actual scanning is delegated to a Scanner instance attached to an
+    ApeStorage.  The delegation permits scanning to occur on a ZEO
+    server while the ScanControl instances exist on ZEO clients.
+
+    Assigns scanner-specific identities to database connections for
+    the purpose of tracking which OIDs are still in use.
+    """
 
     def __init__(self, db=None, scan_interval=10):
         self.db = db
@@ -44,6 +54,8 @@
 
 
     def newConnection(self):
+        """Returns a ConnectionScanControl to attach to a new connection.
+        """
         self.lock.acquire()
         try:
             conn_id = self.next_conn_id
@@ -54,6 +66,10 @@
 
 
     def setConnectionOIDs(self, conn_id, oids):
+        """Records the OIDs a connection is using and periodically scans.
+
+        Scans only if a timeout for the whole connection pool has elapsed.
+        """
         changed = 0
         new_oids = OOSet()
         self.lock.acquire()
@@ -72,10 +88,12 @@
             self.lock.release()
         if changed:
             self.scanner.setOIDs(new_oids)
-        self.mayScan()
+        self._mayScan()
 
 
-    def mayScan(self):
+    def _mayScan(self):
+        """Scans for changes if the scanning interval has elapsed.
+        """
         now = time()
         if now >= self.next_scan:
             self.next_scan = now + self.scan_interval
@@ -85,6 +103,7 @@
             LOG('Ape', DEBUG,
                 'Finished scanning. %d objects changed.' % len(inv))
             if inv:
+                # Some objects changed and the caches need to be invalidated.
                 d = {}
                 for oid in inv:
                     d[oid] = 1
@@ -95,13 +114,22 @@
 
 
 class ConnectionScanControl:
+    """Scanning for a database connection (an ApeConnection.)
+
+    Delegates to a ScanControl, which in turn delegates to a Scanner.
+    """
 
     def __init__(self, ctl, conn_id):
         self.ctl = ctl
         self.conn_id = conn_id
         self.next_update = 0
 
-    def ready(self):
+    def elapsed(self):
+        """Returns true if the connection-specific scan interval has elapsed.
+
+        The interval is designed to prevent connections from calling
+        scanOIDs() with excessive frequency.
+        """
         now = time()
         if now >= self.next_update:
             self.next_update = now + self.ctl.scan_interval
@@ -109,10 +137,16 @@
         return 0
 
     def setOIDs(self, oids):
+        """Records the OIDs this connection is using.
+        """
         self.ctl.setConnectionOIDs(self.conn_id, oids)
 
 
 class Scanner:
+    """Scanning for an ApeStorage.
+
+    Uses gateways to scan for changes.
+    """
 
     def __init__(self):
         self.current = OOBTree()  # OOBTree({ oid -> {source->state} })
@@ -122,10 +156,18 @@
         self.storage = None
 
     def setStorage(self, s):
-        # This is needed for calling storage.getPollSources().
+        """Attaches this scanner to an ApeStorage.
+
+        This must be called before storage.getPollSources() will work.
+        """
         self.storage = s
 
     def setOIDs(self, oids):
+        """Sets the list of OIDs to scan.
+
+        Gathers source information about new OIDs and discards
+        source information for OIDs no longer in use.
+        """
         new_sources = {}  # { oid -> sourcedict }
         self.lock.acquire()
         try:
@@ -170,6 +212,13 @@
 
 
     def setPollSources(self, oid, sources):
+        """Sets the poll sources for one OID.
+
+        This method lets ApeStorage provide the source information
+        before it is actually requested, which might make the system
+        faster overall.  The source information is recorded in either
+        the 'current' or 'future' table.
+        """
         if sources is None:
             sources = {}
         self.lock.acquire()
@@ -185,6 +234,8 @@
 
 
     def setUncommittedSources(self, tid, oid, sources):
+        """Records source information that should only be used after commit.
+        """
         self.lock.acquire()
         try:
             t = self.uncommitted.setdefault(tid, {})
@@ -194,6 +245,8 @@
 
 
     def scan(self):
+        """Scan sources, returning the OIDs of changed objects.
+        """
         to_scan = {}        # { repo -> { source -> state } }
         to_invalidate = {}  # { oid -> 1 }
         self.lock.acquire()  # lock because oid_states might be self.current.
@@ -225,6 +278,10 @@
 
 
     def pruneFuture(self):
+        """Prunes the cache of future source information.
+
+        See setPollSources().
+        """
         if self.future:
             self.lock.acquire()
             try:
@@ -240,6 +297,8 @@
 
 
     def afterCommit(self, tid):
+        """Commits information recorded by setUncommittedSources().
+        """
         self.lock.acquire()
         try:
             if not self.uncommitted.has_key(tid):
@@ -270,6 +329,8 @@
 
 
     def afterAbort(self, tid):
+        """Aborts information recorded by setUncommittedSources().
+        """
         self.lock.acquire()
         try:
             if self.uncommitted.has_key(tid):




More information about the Zope-CVS mailing list