netobj/src/netobjrt/NetObjRT.i3

 Copyright 1992 Digital Equipment Corporation.               
 Distributed only by permission.                             
 NetObjRT.i3 
 Last modified on Wed Apr 14 10:00:34 PDT 1993 by wobber     
      modified on Sun Nov 29 14:13:50 1992 by gnelson    
      modified on Wed Aug  5 17:49:51 PDT 1992 by evers  


 The NetObjRT interface defines procedures which are necessary for
   the maintenance of the network object runtime {\it object table}.
   This table is a mapping from WireRep.T to NetObj.T.  All
   surrogate objects appear in this table, as do all concrete objects
   which might be remotely referenced. 
   

INTERFACE NetObjRT;

IMPORT NetObj, StubLib, Thread, Transport, WireRep;

PROCEDURE FindTarget(
    wrep: WireRep.T;
    stubProt: StubLib.StubProtocol;
    VAR dispatcher: StubLib.Dispatcher) : NetObj.T
  RAISES {NetObj.Error};

 FindTarget searches the object table for an object matching wrep. 
   If one is found, and it is a concrete object, then the object is 
   returned along with the StubLib.Dispatcher procedure corrsponding 
   to its type and to the supplied stubProt.  Otherwise, NetObj.Error
   is raised with the argument NetObj.MissingObject.  (We might want
   to raise an explicit error here if the object exists but no dispatcher
   matching stubProt is found.)


   FindTarget is intended for use only when the supplied wrep is 
   expected to correspond to a local concrete object.  This is the 
   case, for example, when the network object runtime unmarshals the 
   target object of a remote invocation. 
   

PROCEDURE Find(
    wrep: WireRep.T;
    loc: Transport.Location) : NetObj.T
  RAISES {NetObj.Error, Thread.Alerted};

 Find searches the object table for an object matching wrep.
   If one is found, it is returned.  Otherwise, a surrogate object
   is constructed for wrep.  loc must generate connections back to
   the party who provided wrep.  This need not be the owner of the
   concrete object, but if not, it must at least be able to provide
   sufficient information to construct a Transport.Location to the
   real owner. This procedure is called as part of unmarshalling a
   NetObj.T.
   

   If wrep is WireRep.NullT, then Find produces undefined results. 


PROCEDURE InsertAndPin(o: NetObj.T) : WireRep.T;

 If o is not registered in the local object table, InsertAndPin 
   assigns a wire representation to o and inserts it into the table. 
   (This can happen only for concrete objects.)  In all cases, the 
   wire representation of o is returned.  This procedure is called 
   as part of marshalling a NetObj.T.
   

   InsertAndPin increments a reference count associated with o 
   which {\it pins} it in the object table, this is, o is considered 
   unremovable.  When marshalling of o is complete, and the 
   destination is known to have either successfully unmarshalled o 
   or failed in doing so, then this reference count must be decremented 
   with Unpin.
   

   It is a checked runtime error for o to be NIL. 


PROCEDURE Unpin(READONLY arr: ARRAY OF NetObj.T);

 Unpin decrements the pin count associated with each element of
   arr.  When this count becomes zero for any object, that object
   can be removed from the object table (by some surrogate-holder
   reporting in clean).
   

   It is a checked runtime error for any element of arr to be NIL,
   or to have a pin count of zero. 


END NetObjRT.