|
|
| Line 1: |
Line 1: |
| - | For more context see [http://www.erights.org/elib/concurrency/refmech.html] (XXX to be integrated) | + | Placeholder page. For now see [http://www.erights.org/elib/concurrency/refmech.html] |
| | | | |
| - | A SturdyRef is a reference to an object in another vat (henceforth called the host vat) which does not break on network failure or [[vat incarnation death]] as [[live ref]]s do.
| + | ---- |
| - | | + | [[stub]] |
| - | The SturdyRef itself is a [[near ref]], an ordinary local object. SturdyRefs are [[Selfless]] but not [[Transparent]].
| + | |
| - | | + | |
| - | A SturdyRef refers to something in the host vat by a [[swiss number]]; the host vat may at any time change or forget the number/referent association.
| + | |
| - | | + | |
| - | SturdyRefs map one-to-one to [[CapTP URL]]s; the conversion is provided by <code>[[captp__uriGetter|<captp>]]</code>.
| + | |
| - | | + | |
| - | == Protocol ==
| + | |
| - | | + | |
| - | ===getRcvr (both /0 and /2) ===
| + | |
| - | | + | |
| - | Returns a promise for a [[live ref]] to the referent of this SturdyRef.
| + | |
| - | | + | |
| - | The promise can break if:
| + | |
| - | * A connection attempt fails (for /0), or the timeout is reached (for /2).
| + | |
| - | * The referent is a broken ref.
| + | |
| - | * The host vat no longer has this object registered for lookup by this SturdyRef (no longer has an entry for this SturdyRef's [[SwissNumber]]).
| + | |
| - | | + | |
| - | This operation can only be done while the local comm system is [[Introducer#onTheAir/0|on the air]]; otherwise it throws XXX specify exception.
| + | |
| - | | + | |
| - | {{instance msgdoc|getRcvr|0||any}}
| + | |
| - | | + | |
| - | If there is not already a connection to the host vat, and this vat cannot ''currently'' connect to the host vat, resolves to a broken ref.
| + | |
| - | | + | |
| - | {{instance msgdoc|getRcvr|2|<var>pollMillis</var> :([[int]] > 0), <var>timeout</var> :([[int]] >= -1)|any}}
| + | |
| - | | + | |
| - | Continuously attempts to connect; doesn't fail unless the absolute time <var>timeout</var> is reached.
| + | |
| - | | + | |
| - | <var>pollMillis</var> is a polling interval hint. (XXX the following is an implementation description; rewrite as spec) Until we have [[VLS rendezvous]] support, the best we can do is poll the attempt to connect to the hosting vat. <var>pollMillis</var> says how often we should do so, and thereby tradeoff CPU/comm against promptness. Once we have VLS rendezvous support, then we will post a long-lived query with the relevant [[VLS]]es, and refresh this query at a frequency determined by those [[VLS]]es, not by our client. This refreshing is also a polling loop, but can be long without impeding the responsiveness of getting connected.
| + | |
| - | | + | |
| - | <var>timeout</var> is the time in [[absMillis]] at which we should give up trying to connect. Once the time has passed, we should resolve the result to broken rather than continuing to poll or refresh. A value of -1 means to keep trying forever.
| + | |
| - | | + | |
| - | == Additional behavior ==
| + | |
| - | | + | |
| - | SturdyRefs print as "<SturdyRef>", unless they are to the current vat, in which case they print as "<SturdyRef to <var>referent</var>>".
| + | |
| - | | + | |
| - | ? introducer.onTheAir(); null
| + | |
| - |
| + | |
| - | ? def [p,r] := Ref.promise()
| + | |
| - | # value: [<Promise>, <Resolver>]
| + | |
| - |
| + | |
| - | ? def sr := makeSturdyRef.temp(p)
| + | |
| - | # value: <SturdyRef>
| + | |
| - |
| + | |
| - | {{XXX|is the above behavior, printing as a far sturdyref until the promise resolves, a bug?}}
| + | |
| - |
| + | |
| - | ? r.resolve("foo")
| + | |
| - | ? sr
| + | |
| - | # value: <SturdyRef to "foo">
| + | |
| - |
| + | |
| - | ? <captp://*10@example.org/24> # a remote sturdyref
| + | |
| - | # value: <SturdyRef>
| + | |
| - | | + | |
| - | | + | |
| - | == Implementation ==
| + | |
| - | | + | |
| - | A SturdyRef needs to store the same components as a [[CapTP URL]] ([[search path]], host [[VatID]], and [[swiss number]]), plus the [[LocatorUnum]] so that it can get the live ref to return.
| + | |
| - | | + | |
| - | {{stub}}
| + | |
| - | [[Category:ELib specification]]
| + | |
| - | [[Category:Incomplete specifications]]
| + | |
| - | [[Category:Pluribus]]
| + | |
