Source Code for Module foolscap.ipb

  1   
  2   
  3  from zope.interface import interface 
  4  Interface = interface.Interface 
  5   
  6  # TODO: move these here 
  7  from foolscap.tokens import ISlicer, IRootSlicer, IUnslicer 
  8  _ignored = [ISlicer, IRootSlicer, IUnslicer] # hush pyflakes 
  9   
 10 -class DeadReferenceError(Exception): 
 11      """The RemoteReference is dead, Jim.""" 
 12   
 13   
 14 -class IReferenceable(Interface): 
 15      """This object is remotely referenceable. This means it is represented to 
 16      remote systems as an opaque identifier, and that round-trips preserve 
 17      identity. 
 18      """ 
 19   
 20 -    def processUniqueID(): 
 21          """Return a unique identifier (scoped to the process containing the 
 22          Referenceable). Most objects can just use C{id(self)}, but objects 
 23          which should be indistinguishable to a remote system may want 
 24          multiple objects to map to the same PUID.""" 
 25   
 26 -class IRemotelyCallable(Interface): 
 27      """This object is remotely callable. This means it defines some remote_* 
 28      methods and may have a schema which describes how those methods may be 
 29      invoked. 
 30      """ 
 31   
 32 -    def getInterfaceNames(): 
 33          """Return a list of RemoteInterface names to which this object knows 
 34          how to respond.""" 
 35   
 36 -    def doRemoteCall(methodname, args, kwargs): 
 37          """Invoke the given remote method. This method may raise an 
 38          exception, return normally, or return a Deferred.""" 
 39   
 40 -class ITub(Interface): 
 41      """This marks a Tub.""" 
 42   
 43 -class IBroker(Interface): 
 44      """This marks a broker.""" 
 45   
 46 -class IRemoteReference(Interface): 
 47      """This marks a RemoteReference.""" 
 48   
 49 -    def notifyOnDisconnect(callback, *args, **kwargs): 
 50          """Register a callback to run when we lose this connection. 
 51   
 52          The callback will be invoked with whatever extra arguments you 
 53          provide to this function. For example:: 
 54   
 55           def my_callback(name, number): 
 56               print name, number+4 
 57           cookie = rref.notifyOnDisconnect(my_callback, 'bob', number=3) 
 58   
 59          This function returns an opaque cookie. If you want to cancel the 
 60          notification, pass this same cookie back to dontNotifyOnDisconnect:: 
 61   
 62           rref.dontNotifyOnDisconnect(cookie) 
 63   
 64          Note that if the Tub is shutdown (via stopService), all 
 65          notifyOnDisconnect handlers are cancelled. 
 66          """ 
 67   
 68 -    def dontNotifyOnDisconnect(cookie): 
 69          """Deregister a callback that was registered with notifyOnDisconnect. 
 70          """ 
 71   
 72 -    def callRemote(name, *args, **kwargs): 
 73          """Invoke a method on the remote object with which I am associated. 
 74   
 75          I always return a Deferred. This will fire with the results of the 
 76          method when and if the remote end finishes. It will errback if any of 
 77          the following things occur:: 
 78   
 79           the arguments do not match the schema I believe is in use by the 
 80           far end (causes a Violation exception) 
 81   
 82           the connection to the far end has been lost (DeadReferenceError) 
 83   
 84           the arguments are not accepted by the schema in use by the far end 
 85           (Violation) 
 86   
 87           the method executed by the far end raises an exception (arbitrary) 
 88   
 89           the return value of the remote method is not accepted by the schema 
 90           in use by the far end (Violation) 
 91   
 92           the connection is lost before the response is returned 
 93           (ConnectionLost) 
 94   
 95           the return value is not accepted by the schema I believe is in use 
 96           by the far end (Violation) 
 97          """ 
 98   
 99 -    def callRemoteOnly(name, *args, **kwargs): 
100          """Invoke a method on the remote object with which I am associated. 
101   
102          This form is for one-way messages that do not require results or even 
103          acknowledgement of completion. I do not wait for the method to finish 
104          executing. The remote end will be instructed to not send any 
105          response. There is no way to know whether the method was successfully 
106          delivered or not. 
107   
108          I always return None. 
109          """ 
110