SturdyRef
From Erights
Kevin Reid (Talk | contribs) (consistent categorization) |
(add some test cases I found) |
||
| (4 intermediate revisions not shown) | |||
| Line 11: | Line 11: | ||
== Protocol == | == Protocol == | ||
| - | + | ===getRcvr (both /0 and /2) === | |
Returns a promise for a [[live ref]] to the referent of this SturdyRef. | 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. | 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| | + | {{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>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 | + | <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> | ||
Latest revision as of 22:26, 14 May 2009
For more context see [1] (XXX to be integrated)
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 refs do.
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 URLs; the conversion is provided by <captp>.
Contents |
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 on the air; otherwise it throws XXX specify exception.
getRcvr/0
- Signature: getRcvr() :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.
getRcvr/2
Continuously attempts to connect; doesn't fail unless the absolute time timeout is reached.
pollMillis 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. pollMillis 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 VLSes, and refresh this query at a frequency determined by those VLSes, not by our client. This refreshing is also a polling loop, but can be long without impeding the responsiveness of getting connected.
timeout 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 referent>".
? 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.
- 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.
