[Zodb-checkins] CVS: ZODB3/ZEO - ServerStub.py:1.17.2.1

[Jeremy Hylton]

Update of /cvs-repository/ZODB3/ZEO
In directory cvs.zope.org:/tmp/cvs-serv28665/ZEO

Modified Files:
      Tag: ZODB3-mvcc-2-branch
	ServerStub.py 
Log Message:
Add some documentation to the storage stubs.


=== ZODB3/ZEO/ServerStub.py 1.17 => 1.17.2.1 ===
--- ZODB3/ZEO/ServerStub.py:1.17	Thu Oct  2 14:17:22 2003
+++ ZODB3/ZEO/ServerStub.py	Tue Nov  4 17:19:45 2003
@@ -13,6 +13,18 @@
 ##############################################################################
 """RPC stubs for interface exported by StorageServer."""
 
+##
+# ZEO storage server.
+# <p>
+# Remote method calls can be synchronous or asynchronous.  If the call
+# is synchronous, the client thread blocks until the call returns.  A
+# single client can only have one synchronous request outstanding.  If
+# several threads share a single client, threads other than the caller
+# will block only if the attempt to make another synchronous call.
+# An asynchronous call does not cause the client thread to block.  An
+# exception raised by an asynchronous method is logged on the server,
+# but is not returned to the client.
+
 class StorageServer:
 
     """An RPC stub class for the interface exported by ClientStorage.
@@ -43,46 +55,134 @@
     def extensionMethod(self, name):
         return ExtensionMethodWrapper(self.rpc, name).call
 
+    ##
+    # Register current connection with a storage and a mode.
+    # In effect, it is like an open call.
+    # @param storage_name a string naming the storage.  This argument
+    #        is primarily for backwards compatibility with servers
+    #        that supported multiple storages.
+    # @param read_only boolean
+    # @exception ValueError unknown storage_name or already registered
+    # @exception ReadOnlyError storage is read-only and a read-write
+    #            connectio was requested
+
     def register(self, storage_name, read_only):
         self.rpc.call('register', storage_name, read_only)
 
+    ##
+    # Return dictionary of meta-data about the storage.
+    # @defreturn dict
+
     def get_info(self):
         return self.rpc.call('get_info')
 
+    ##
+    # Check whether the server requires authentication.  Returns
+    # the name of the protocol.
+    # @defreturn string
+
     def getAuthProtocol(self):
         return self.rpc.call('getAuthProtocol')
 
+    ##
+    # Return id of the last committed transaction
+    # @defreturn string
+
     def lastTransaction(self):
         # Not in protocol version 2.0.0; see __init__()
         return self.rpc.call('lastTransaction')
 
+    ##
+    # Return invalidations for all transactions after tid.
+    # @param tid transaction id
+    # @defreturn 2-tuple, (tid, list)
+    # @return tuple containing the last committed transaction
+    #         and a list of oids that were invalidated.  Returns
+    #         None and an empty list if the server does not have
+    #         the list of oids available.
+
     def getInvalidations(self, tid):
         # Not in protocol version 2.0.0; see __init__()
         return self.rpc.call('getInvalidations', tid)
 
+    ##
+    # Check whether serial numbers s and sv are current for oid.
+    # If one or both of the serial numbers are not current, the
+    # server will make an asynchronous invalidateVerify() call.
+    # @param oid object id
+    # @param s serial number on non-version data
+    # @param sv serial number of version data or None
+    # @defreturn async
+
     def zeoVerify(self, oid, s, sv):
         self.rpc.callAsync('zeoVerify', oid, s, sv)
 
+    ##
+    # Signal to the server that cache verification is done.
+    # @defreturn async
+
     def endZeoVerify(self):
         self.rpc.callAsync('endZeoVerify')
 
+    ##
+    # Generate a new set of oids.
+    # @param n number of new oids to return
+    # @defreturn list
+    # @return list of oids
+
     def new_oids(self, n=None):
         if n is None:
             return self.rpc.call('new_oids')
         else:
             return self.rpc.call('new_oids', n)
 
+    ##
+    # Pack the storage.
+    # @param t pack time
+    # @param wait optional, boolean.  If true, the call will not
+    #             return until the pack is complete.
+
     def pack(self, t, wait=None):
         if wait is None:
             self.rpc.call('pack', t)
         else:
             self.rpc.call('pack', t, wait)
 
+    ##
+    # Return current data for oid.  Version data is returned if
+    # present.
+    # @param oid
+    # @defreturn 5-tuple
+    # @return 5-tuple, current non-version data, serial number,
+    #         version name, version data, version data serial number
+
     def zeoLoad(self, oid):
         return self.rpc.call('zeoLoad', oid)
 
+    def load(self, oid, version):
+        pass
+
+    ##
+    # Storage new revision of oid.
+    # @param oid object id
+    # @param serial serial number that this transaction read
+    # @param data new data record for oid
+    # @param version name of version or ""
+    # @param id id of current transaction
+    # @defreturn async
+
     def storea(self, oid, serial, data, version, id):
         self.rpc.callAsync('storea', oid, serial, data, version, id)
+
+    ##
+    # Start two-phase commit for a transaction
+    # @param id id used by client to identify current transaction
+    # @param user name of user committing transaction (can be "")
+    # @param description string containing transaction metadata (can be "")
+    # @param ext dictionary of extended metadata (?)
+    # @param tid optional explicit tid to pass to underlying storage
+    # @param status optional status character, e.g "p" for pack
+    # @defreturn async
 
     def tpc_begin(self, id, user, descr, ext, tid, status):
         return self.rpc.call('tpc_begin', id, user, descr, ext, tid, status)