[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[minion-cvs] Document some new functions introduced for 0.0.7: clean...



Update of /home/minion/cvsroot/src/minion/lib/mixminion
In directory moria.mit.edu:/tmp/cvs-serv15820/lib/mixminion

Modified Files:
	BuildMessage.py MMTPClient.py TLSConnection.py 
Log Message:
Document some new functions introduced for 0.0.7: clean code is happy code.

(BTW, we seem to have crossed the 35 kloc mark at some point: when did
that happen?  This was supposed to be such a simple project!  Fortunately,
more than half of that is still in tests and comments.)


Index: BuildMessage.py
===================================================================
RCS file: /home/minion/cvsroot/src/minion/lib/mixminion/BuildMessage.py,v
retrieving revision 1.69
retrieving revision 1.70
diff -u -d -r1.69 -r1.70
--- BuildMessage.py	16 Feb 2004 22:30:03 -0000	1.69
+++ BuildMessage.py	16 Feb 2004 22:50:38 -0000	1.70
@@ -343,12 +343,12 @@
                 SURB keys. For backward compatibility, 'userKeys' may also be
                 None (no SURBs known), a dict (from name to key), or a single
                 key (implied identity is "").
+           retNym: If present, and if the payload was a reply, we call
+                retNym.append(pseudonym)
 
        If we can successfully decrypt the payload, we return it.  If we
        might be able to decrypt the payload given more/different keys,
        we return None.  If the payload is corrupt, we raise MixError.
-
-       DOCDOC retNym
     """
     if userKeys is None:
         userKeys = []

Index: MMTPClient.py
===================================================================
RCS file: /home/minion/cvsroot/src/minion/lib/mixminion/MMTPClient.py,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -d -r1.54 -r1.55
--- MMTPClient.py	15 Feb 2004 23:25:33 -0000	1.54
+++ MMTPClient.py	16 Feb 2004 22:50:38 -0000	1.55
@@ -80,6 +80,8 @@
     # _isConnected: flag: true if the TLS connection been completed,
     #   and no errors have been encountered.
     # _isFailed: flag: has this connection encountered any errors?
+    # _isAlive: flag: if we put another packet on this connection, will the
+    #   packet maybe get delivered?
 
     ####
     # External interface
@@ -126,7 +128,7 @@
         self.nPacketsSent = self.nPacketsAcked = self.nPacketsTotal =0
         self._isConnected = 0
         self._isFailed = 0
-        self._isAlive = 1 #DOCDOC
+        self._isAlive = 1
         EventStats.log.attemptedConnect()
         LOG.debug("Openining client connection to %s",self.address)
         self.beginConnecting()

Index: TLSConnection.py
===================================================================
RCS file: /home/minion/cvsroot/src/minion/lib/mixminion/TLSConnection.py,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- TLSConnection.py	7 Feb 2004 17:11:30 -0000	1.12
+++ TLSConnection.py	16 Feb 2004 22:50:38 -0000	1.13
@@ -16,6 +16,8 @@
 _READLEN = 1024
 
 class _Closing(Exception):
+    """Helper class: exception raised by state functions that want the
+       TLS connection to be closed."""
     pass
 
 class TLSConnection:
@@ -57,6 +59,10 @@
     #   the first time we called shutdown.
     # __readBlockedOnWrite, __writeBlockedOnRead -- flags: has a read/write
     #   operation blocked on the opposite event type?
+    # __blockedWriteLen -- if the last call to 'write' blocked, how much
+    #   did we try to write?  (OpenSSL requires that we retry using exactly
+    #   the same length as the time before.)  0 if the last write was
+    #   successful.
 
     def __init__(self, tls, sock, address):
         """Create a new TLSConnection."""
@@ -341,9 +347,13 @@
         "Helper function: write as much data from self.outbuf as we can."
         self.__writeBlockedOnRead = 0
         while self.outbuf and cap > 0:
-            if self.__blockedWriteLen: #DOCDOC
+            if self.__blockedWriteLen:
+                # If the last write blocked, we must retry the exact same
+                # length, or else OpenSSL will give an error.
                 span = self.__blockedWriteLen
             else:
+                # Otherwise, we try to write as much of the first string on
+                # the output buffer as our bandwidth cap will allow.
                 span = min(len(self.outbuf[0]),cap)
             try:
                 n = self.tls.write(self.outbuf[0][:span])
@@ -398,7 +408,8 @@
                     cap -= len(s)
                     if (not self.tls.pending()) and cap > 0:
                         # Only call onRead when we've got all the pending
-                        # data from self.tls. DOCDOC cap
+                        # data from self.tls, or we've just run out of
+                        # allocated bandwidth.
                         self.onRead()
             except _ml.TLSWantRead:
                 self.wantRead = 1
@@ -410,10 +421,10 @@
 
     def process(self, r, w, x, maxBytes=None):
         """Given that we've received read/write events as indicated in r/w,
-           advance the state of the connection as much as possible.  Return
-           is as in 'getStatus'.
-
-           DOCDOC cap."""
+           advance the state of the connection as much as possible, but try to
+           use no more than 'maxBytes' bytes of bandwidth. Return
+           is as in 'getStatus', with an extra 'bandwidth used' field
+           appended."""
         if x and (self.sock is not None):
             self.__close(gotClose=1)
             return 0,0,0,0
@@ -444,7 +455,9 @@
             else:
                 self.wantWrite = 1
         except _Closing:
-            #DOCDOC
+            # state functions that want to close the connection should
+            # raise '_Closing', so we can count the bytes used before we
+            # call 'close'.
             if self.tls is not None:
                 bytesNow = self.tls.get_num_bytes_raw()
             self.__close()
@@ -474,7 +487,6 @@
 
     def getStatus(self):
         """Return a 3-tuple of wantRead, wantWrite, and isOpen."""
-        #DOCDOC
         return self.wantRead, self.wantWrite, (self.sock is not None)
 
     #####
@@ -498,7 +510,7 @@
         raise NotImplemented()
 
     def onTimeout(self):
-        """DOCDOC"""
+        """Called when the connection gets timed out."""
         raise NotImplemented()
 
     def onClosed(self):