PassByConstruction

From Erights

(Difference between revisions)
Jump to: navigation, search
m (Example)
(revert)
 
(11 intermediate revisions not shown)
Line 1: Line 1:
-
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.
+
A PassByConstruction (also 'pbc') object is one which, when sent over a [[comm system]] (e.g. [[CapTP]]) to another vat, is sent as some serialized representation, and will typically arive [[near]] rather than as a [[far reference]] back to the originating vat ([[PassByProxy]]).
-
To mark an object as pbc, it has to implement the interface pbc:
+
 
 +
{{XXX|Are there any references neither PBP nor PBC?}}
 +
 
 +
PassByConstruction objects may additionally be [[Selfless]], which by definition makes them [[PassByCopy]], i.e. exactly duplicated. On the other hand, [[Selfish]] PassByConstruction objects are used, for example, for [[una]].  
 +
 
 +
==Defining pass-by-construction objects==
 +
 
 +
E [[comm system]]s serialize any object approved by the <code>pbc</code> auditor as the [[portrayal]] returned by its [[Miranda optUncall|__optUncall/0]] method. For example, this is an object which will always arrive as the number 3:
<code>
<code>
     def foo implements pbc {
     def foo implements pbc {
-
         to __optUncall() { return [1, "add", [2]] }
+
         to [[Miranda optUncall|__optUncall]]() { return [1, "add", [2]] }
         # ...
         # ...
     }
     }
</code>
</code>
-
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]].
+
===Example===
-
 
+
-
The triple returned by __optUncall has this format:
+
-
<pre>
+
-
[constructor, method, args]
+
-
</pre>
+
-
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.
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"
+
This code should be positioned in an [[emaker]] file in the java classpath at the location "tests/makeVector.emaker"
<pre>def makeVector implements pbc {
<pre>def makeVector implements pbc {
Line 51: Line 49:
# function for creating a new local vat
# function for creating a new local vat
-
? def seedVatAuthor := &lt;elang:interp.seedVatAuthor&gt;(&lt;unsafe&gt;).virtualize((introducer))
+
? def seedVatAuthor := &lt;elang:interp.seedVatAuthor&gt;(&lt;unsafe&gt;).virtualize(introducer)
# value: &lt;virtualSeedVat&gt;
# value: &lt;virtualSeedVat&gt;
Line 67: Line 65:
? Thing: &lt;Vector 6.6 7.7&gt;</pre>
? Thing: &lt;Vector 6.6 7.7&gt;</pre>
 +
 +
{{stub}}
 +
[[Category:ELib specification]]

Latest revision as of 22:48, 20 April 2011

A PassByConstruction (also 'pbc') object is one which, when sent over a comm system (e.g. CapTP) to another vat, is sent as some serialized representation, and will typically arive near rather than as a far reference back to the originating vat (PassByProxy).

XXX Are there any references neither PBP nor PBC?

PassByConstruction objects may additionally be Selfless, which by definition makes them PassByCopy, i.e. exactly duplicated. On the other hand, Selfish PassByConstruction objects are used, for example, for una.

Defining pass-by-construction objects

E comm systems serialize any object approved by the pbc auditor as the portrayal returned by its __optUncall/0 method. For example, this is an object which will always arrive as the number 3:

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

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 an emaker 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>
# 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>
This page is a stub; it should be expanded with more information. If doing so, check the original E web site and the mailing list archives for content which could be moved into this page.
Personal tools
more tools