# Copyright 2002 Combex, Inc. under the terms of the MIT X license
# found at http://www.opensource.org/licenses/mit-license.html ...............

pragma.syntax("0.9")

def VatID :DeepFrozen := <import:net.captp.protocol.VatID>

/**
 * Each product of this maker represents a presence of the pervasive LocatorUnum service.
 *
 * For Una in general: To hold a reference to any presence of the Unum is conceptually to hold a reference to the Unum as a whole. Therefore, a reference to the Unum may as well always be a reference to a local presence of the Unum. Since it can be, and since this would provide better service, we specify that all references to an Unum will be local.
 * 
 * Therefore, an encoded reference to a presence of Unum that's local to the sending side will be decoded as a reference to a presence of the same Unum local to the receiving side. Therefore, a fulfilled reference to an Unum is always <a href="http://www.erights.org/elib/concurrency/refmech.html">Near</a>, and therefore a reference to an Unum is always eventually Near or Broken.
 * 
 * The LocatorUnum is the only Unum built into E itself. It represents the pervasive vatID/swissNumber lookup service built jointly out of all vats and VLSes. It is used only by SturdyRefs to establish their authority to perform a lookup, and to enable SturdyRefs to maintain this authority as they are copied between vats.
 * 
 * The locatorUnum instance should be a graph exit in every connection in the CapTP system; it does not itself provide __optUncall (which would reveal the swiss table and CapTPMgr).
 *
 * @author Mark S. Miller
 */
def makeLocatorUnum(myVatID, swissTable, hub) implements DeepFrozen, ExitViaHere {

    return def locatorUnum {

        /**
         * The basic operation underlying 'SturdyRef.getRcvr()'.
         * <p/>
         * This is where a reference to a remote object actually gets the various
         * underlying comm systems connected so that we can send messages.
         * <p/>
         * getRcvr only works when we're {@link Introducer#onTheAir onTheAir}.
         *
         * @param searchPath A list of places to try to find the vat
         * @param vatID      The vat from which the object reference should be
         *                   obtained
         * @param swissNum   The SwissNumber of the desired object
         * @param optFarVine Optional object for holding onto a Remote reference
         *                   via whoever we got it from long enough to fetch our
         *                   own Remote reference via this lookup.
         */
        to getRcvr(searchPath :List[String],
                   vatID :VatID,
                   swissNum :int,
                   optFarVine :any) :any {
            if (true) { # XXX was "Trace.captp.debug && Trace.ON" in EoJ
                traceln(`$locatorUnum.getRcvr($searchPath, $vatID, $swissNum, $optFarVine)`)
            }
            if (!Ref.isResolved(myVatID)) {
                throw("introducer not yet identified")
            } else if (vatID == myVatID) {

                #if we are following into the local vat, do a local lookup.
                #If not found, it'll throw an IndexOutOfBoundsException
                # XXX switch to ejector for sealed-throw rules
                return swissTable.lookupSwiss(swissNum)
            }
            if (!Ref.isResolved(hub)) {
                throw("Must first be onTheAir")
            }
            def outgoingConn := hub[searchPath, vatID]
            # XXX should be called getRemoteNonceLocator/0 (since EoJ does and there's nothing wrong with the name)
            def remoteNonceLocator := outgoingConn.nonceLocator()
            return remoteNonceLocator <- lookupSwiss(swissNum, optFarVine)
        }
    }
}