SturdyRef - Revision history

Kevin Reid: add some test cases I found

Kevin Reid — Thu, 14 May 2009 22:26:12 GMT

add some test cases I found

New page

For more context see [http://www.erights.org/elib/concurrency/refmech.html] (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 ref]]s 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 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]]

Kevin Reid: describe getRcvr in general; clarify broken results; clarify differences between /0 and /2

Kevin Reid — Sat, 11 Oct 2008 17:18:17 GMT

describe getRcvr in general; clarify broken results; clarify differences between /0 and /2

←Older revision		Revision as of 17:18, 11 October 2008
Line 11:		Line 11:
	== Protocol ==		== Protocol ==

-	~~{{instance msgdoc\|~~getRcvr\|0~~\|\|any}}~~	+	===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.

-	~~If this vat cannot ''currently'' connect to the host vat~~, ~~then~~ the ~~result will resolve to~~ a [[broken ref~~]]; however, a broken ref can also be what the~~ host vat ~~returns as the referent.~~ (~~XXX do we want to provide~~ for ~~distinguishing these cases?~~)	+	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\|~~2\|<var>pollMillis</var> :([[int]] >~~ 0~~), <var>timeout</var> :([[int]] >= -1)~~\|any}}	+	{{instance msgdoc\|getRcvr\|0\|\|any}}

-	~~(XXX this text~~ is ~~copied with changes from~~ the ~~old JavaDoc; see notes)~~	+	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.

-	~~Like~~ getRcvr(~~) but doesn't resolve the result until we connect to the object's hosting vat. (XXX what is the observable distinction of "doesn't resolve...until..."? What does getRcvr/~~0 ~~do differently?~~)	+	{{instance msgdoc\|getRcvr\|2\|<var>pollMillis</var> :([[int]] > 0), <var>timeout</var> :([[int]] >= -1)\|any}}
-	~~Note that the result may still resolve to broken~~, ~~if the object's hosting vat, for example, no longer has this object registered for lookup by this SturdyRef~~ (~~no longer has an entry for this SturdyRef's~~ [[~~SwissNumber~~]])~~. (XXX isn't this true for both?)~~	+

-	~~This operation can only be done while~~ the ~~local comm system~~ is ~~[[Introducer#onTheAir/0\|on the air]]; otherwise it throws XXX specify exception~~.	+	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 ~~absMillis (since the~~ [[~~epoch~~]]) 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.	+	<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.
-		+
-	~~This operation can only be done while the local comm system is [[Introducer#onTheAir/0\|on the air]]; otherwise it throws XXX specify exception.~~	+
-		+

	== Implementation ==		== Implementation ==

Kevin Reid: consistent categorization

Kevin Reid — Sat, 11 Oct 2008 00:53:34 GMT

consistent categorization

←Older revision		Revision as of 00:53, 11 October 2008
Line 42:		Line 42:
	[[Category:ELib specification]]		[[Category:ELib specification]]
	[[Category:Incomplete specifications]]		[[Category:Incomplete specifications]]
-	[[Category:~~CapTP~~]]	+	[[Category:Pluribus]]

Kevin Reid at 00:38, 11 October 2008

Kevin Reid — Sat, 11 Oct 2008 00:38:35 GMT

←Older revision		Revision as of 00:38, 11 October 2008
Line 1:		Line 1:
	For more context see [http://www.erights.org/elib/concurrency/refmech.html] (XXX to be integrated)		For more context see [http://www.erights.org/elib/concurrency/refmech.html] (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 death]].	+	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.

	The SturdyRef itself is a [[near ref]], an ordinary local object. SturdyRefs are [[Selfless]] but not [[Transparent]].		The SturdyRef itself is a [[near ref]], an ordinary local object. SturdyRefs are [[Selfless]] but not [[Transparent]].
Line 42:		Line 42:
	[[Category:ELib specification]]		[[Category:ELib specification]]
	[[Category:Incomplete specifications]]		[[Category:Incomplete specifications]]
		+	[[Category:CapTP]]

Kevin Reid: less stubby

Kevin Reid — Fri, 10 Oct 2008 19:54:30 GMT

less stubby

←Older revision		Revision as of 19:54, 10 October 2008
Line 1:		Line 1:
-	~~Placeholder page.~~ For ~~now~~ see [http://www.erights.org/elib/concurrency/refmech.html]	+	For more context see [http://www.erights.org/elib/concurrency/refmech.html] (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 death]].
		+
		+	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 ==
		+
		+	{{instance msgdoc\|getRcvr\|0\|\|any}}
		+
		+	Returns a promise for a [[live ref]] to the referent of this SturdyRef.
		+
		+	If this vat cannot ''currently'' connect to the host vat, then the result will resolve to a [[broken ref]]; however, a broken ref can also be what the host vat returns as the referent. (XXX do we want to provide for distinguishing these cases?)
		+
		+	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\|2\|<var>pollMillis</var> :([[int]] > 0), <var>timeout</var> :([[int]] >= -1)\|any}}
		+
		+	(XXX this text is copied with changes from the old JavaDoc; see notes)
		+
		+	Like getRcvr() but doesn't resolve the result until we connect to the object's hosting vat. (XXX what is the observable distinction of "doesn't resolve...until..."? What does getRcvr/0 do differently?)
		+	Note that the result may still resolve to broken, if the object's hosting vat, for example, no longer has this object registered for lookup by this SturdyRef (no longer has an entry for this SturdyRef's [[SwissNumber]]). (XXX isn't this true for both?)
		+
		+	This operation can only be done while the local comm system is [[Introducer#onTheAir/0\|on the air]]; otherwise it throws XXX specify exception.
		+
		+	<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 (since the [[epoch]]) 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.
		+
		+	This operation can only be done while the local comm system is [[Introducer#onTheAir/0\|on the air]]; otherwise it throws XXX specify exception.
		+
		+
		+	== 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}}		{{stub}}
		+	[[Category:ELib specification]]
		+	[[Category:Incomplete specifications]]

Zarutian: changing references to stub page into reference to template stub

Zarutian — Thu, 18 Sep 2008 22:31:12 GMT

changing references to stub page into reference to template stub

←Older revision		Revision as of 22:31, 18 September 2008
Line 2:		Line 2:

	----		----
-	[[stub]]	+	{{stub}}

Zarutian: placeholder created

Zarutian — Wed, 17 Sep 2008 21:47:40 GMT

placeholder created

←Older revision		Revision as of 21:47, 17 September 2008
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~~]]	+