PassByConstruction

From Erights

When objects are transfered to another vat, they arrive as proxies by default. To reconstruct the object as a local object in the receiving vat, Pass By Construction (pbc) can be used. To mark an object as pbc, it has to implement the interface pbc:

   def foo implements pbc {
       to __optUncall() { return [1, "add", [2]] }
       # ...
   }

The method __optUncall is a miranda method. When the object is passed to another vat, the method __optUncall is called by the CapTP networking subsystem of E. The result of the method is used to reconstruct the object in the destination vat.

The triple returned by __optUncall has this format:

[constructor, method, args]

where constructor is a reference to the maker that is to be used to reconstruct the object in the receiving vat, method is the method of the maker to run and args is a ConstList of arguments.

Example

The first part of the example is a maker for a 2D Vector. The created vectors are Pass By Construction, they should pass the guard :pbc. This code should be positioned in a file in the java classpath at the location "tests/makeVector.emaker"

def makeVector implements pbc {
    to run(var x, var y) {
        def vector implements pbc {
            to getX() :any { return x }
            to getY() :any { return y }
            to __optUncall() :any { return [makeVector, "run", [x,y]] }
            to __printOn(out) {out.print(`<Vector $x $y>`)}
        }
        return vector
    }
    to __optUncall() :any {
        return [<import>, "get", ["tests.makeVector"]]
    }
}

Example of usage:

# create a new Vector object
? def makeVector := <import:tests.makeVector&lgt;
# value: <makeVector>

? def vector := makeVector(6.6,7.7)
# value: <Vector 6.6 7.7>

? introducer.onTheAir()
# value: ["3DES_SDH_M2", "3DES_SDH_M"]

# function for creating a new local vat
? def seedVatAuthor := <elang:interp.seedVatAuthor>(<unsafe>).virtualize((introducer))
# value: <virtualSeedVat>

# Run this source code in the new vat. The method accepts a pbc object and prints it.
? def scriptSource:="def run(thing :pbc) {println(`Thing: $thing`)}"
# value: "def run(thing :near) {println(`Thing: $thing`)}"

# create the new vat. Return a far reference to the object and a reference to the vat object
? def [scriptObj, vat] := seedVatAuthor(scriptSource)
# value: [<Promise>, <Vat newVirtualSeedVat in <runs in newVirtualSeedVat>>]

# pass the pbc object into the new vat
? scriptObj <- run(vector)
# value: <Remote Promise>

? Thing: <Vector 6.6 7.7>