[Zodb-checkins] CVS: ZEO/ZEO/zrpc - client.py:1.1.2.4

[Jeremy Hylton]

Update of /cvs-repository/ZEO/ZEO/zrpc
In directory cvs.zope.org:/tmp/cvs-serv26232

Modified Files:
      Tag: Standby-branch
	client.py 
Log Message:
Add a few comments and doc strings that may help Tim understand the
classes and methods.


=== ZEO/ZEO/zrpc/client.py 1.1.2.3 => 1.1.2.4 ===
         self.connected = 0
         self.connection = None
+        self.closed = 0
         # If _thread is not None, then there is a helper thread
         # attempting to connect.  _thread is protected by _connect_lock.
         self._thread = None
         self._connect_lock = threading.Lock()
         self.trigger = None
         self.thr_async = 0
-        self.closed = 0
         ThreadedAsync.register_loop_callback(self.set_async)
 
     def __repr__(self):
@@ -86,11 +86,24 @@
         self.thr_async = 1 # XXX needs to be set on the Connection
 
     def attempt_connect(self):
-        # XXX will a single attempt take too long?
+        """Attempt a connection to the server without blocking too long.
+
+        There isn't a crisp definition for too long.  When a
+        ClientStorage is created, it attempts to connect to the
+        server.  If the server isn't immediately available, it can
+        operate from the cache.  This method will start the background
+        connection thread and wait a little while to see if it
+        finishes quickly.
+        """
+        
+        # XXX will a single attempt take too long?  
         self.connect()
         try:
             event = self._thread.one_attempt
         except AttributeError:
+            # An AttributeError means that (1) _thread is None and (2)
+            # as a consquence of (1) that the connect thread has
+            # already exited.
             pass
         else:
             event.wait()
@@ -134,9 +147,23 @@
         self.sock = sock
             
 class ConnectThread(threading.Thread):
+    """Thread that tries to connect to server given one or more addresses.
+
+    The thread is passed a ConnectionManager and the manager's client
+    as arguments.  It calls notifyConnected() on the client when a
+    socket connects.  If notifyConnected() returns without raising an
+    exception, the thread is done; it calls connect_done() on the
+    manager and exits.
+
+    The thread will continue to run, attempting connections, until a
+    successful notifyConnected() or stop() is called.
+    """
 
     __super_init = threading.Thread.__init__
 
+    # We don't expect clients to call any methods of this Thread other
+    # than close() and those defined by the Thread API.
+
     def __init__(self, mgr, client, addr, tmin, tmax):
         self.__super_init(name="Connect(%s)" % addr)
         self.mgr = mgr
@@ -146,13 +173,16 @@
         self.tmax = tmax
         self.stopped = 0
         self.one_attempt = threading.Event()
+        # A ConnectThread keeps track of whether it has finished a
+        # call to attempt_connects().  This allows the
+        # ConnectionManager to make an attempt to connect right away,
+        # but not block for too long if the server isn't immediately
+        # available.  
 
     def stop(self):
         self.stopped = 1
 
-    def close_sockets(self):
-        for s in self.sockets.keys():
-            s.close()
+    # Every method from run() to the end is used internally by the Thread.
 
     def run(self):
         delay = self.tmin
@@ -165,6 +195,10 @@
                 delay = self.tmax
         log("thread exiting: %s" % self.getName())
                 
+    def close_sockets(self):
+        for s in self.sockets.keys():
+            s.close()
+
     def attempt_connects(self):
         "Return true if any connect attempt succeeds."
         self.sockets = {}
@@ -216,7 +250,6 @@
 
         If connect_ex() returns EINPROGRESS, we need to try again later.
         """
-
         addr = self.sockets[s]
         e = s.connect_ex(addr)
         if e == errno.EINPROGRESS: