MakeSturdyRef - Revision history

Markm at 16:14, 10 August 2009

Markm — Mon, 10 Aug 2009 16:14:09 GMT

New page

[[makeSturdyRef]], available in the [[privilegedEnv]] is used to register objects so that SturdyRefs to them exist. It differs from [[IdentityMgr]] in that it provides ''persistent'' (when used with [[timeMachine]]) registrations.


"Enables one to make SturdyRefs for objects, even if one is in a distributed
confinement box."

makeSturdyRef isn't itself Persistent, but it is an exit, so a persistent object holding a persistent
pointer to it will likely revive holding the instance from the new vat incarnation.

==Protocol==

{{XXX|Review: Type of expiration date field. Distinguish finite from infinite time.}}

{{instance msgdoc|tearOffRoots|2|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>|[[FlexMap]]}}

Uses the "tear-off" technique for establishing private shared state
between two objects.

The "tear-off" tag can only be torn off once, and once it's torn off
it's apparent that it is to all those who try to do so.

In this case, the tearing off is supposed to happen by the [[TimeMachine]]
when it transitions out of the [[TimeMachine#Ephemeral|Ephemeral]] state. Therefore, if a tearOff
hasn't happened yet, the code here assumes that we're still in the
Ephemeral state and that nothing may be made persistent.

Note: If you want to make something sturdy for purposes of distribution,
but not persistent, use [[IdentityMgr]] or [[#temp/2]] instead.
This requires the [[Introducer]] to be identified, but is independent of the
state of the [[TimeMachine]].

{{instance msgdoc|run|1|<var>obj</var> :[[any]]|[[SturdyRef]]}}

Produce a persistent perpetual [[SturdyRef]] for an object.

Just run/2 with the optExpirationDate defaulting to forever.

* obj: The object for which a SturdyRef is desired
* Returns: A new SturdyRef for the indicated object

{{instance msgdoc|run|2|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]|[[SturdyRef]]}}

Produce a non-cancellable persistent SturdyRef for an object.

{{specbycode|makeSturdyRef.make(obj,optExpirationDate)[0]}}.

{{instance msgdoc|vow|1|<var>obj</var> :[[any]]|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

Produce a vow for a persistent perpetual SturdyRef for an object.

Just vow/2 with the optExpirationDate defaulting to forever.

* obj: The object for which a SturdyRef is desired
* Returns: A vow for a new SturdyRef for the indicated object

{{instance msgdoc|vow|2|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

Produce a vow for a non-cancellable persistent SturdyRef for an object.

Makes the SturdyRef immediately, but only resolves the vow after the
next time the associated timeMachine is saved; so only committed
SturdyRefs are available to be given out.

{{XXX|We should extend the behavior of this to allow it to be called
before the introducer is identified or onTheAir, it which case it should
wait for that before internally making the SturdyRef.}}

* obj: The object for which a SturdyRef is desired
* returns: A vow for a new SturdyRef for the indicated object

{{instance msgdoc|make|1|<var>obj</var> :[[any]]|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}

optExpirationDate defaults to forever.

{{instance msgdoc|make|2|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}

Produce a SturdyRef for a persistence-capable object, thereby making it
persistent.

The SturdyRef will designate the object across time and space, at least
until the expiration time, so long as the hosting vat (this vat) is
accessible.

* obj: The object for which a SturdyRef is desired
* optExpirationDate: The date after which the SturdyRef will not longer be guaranteed to be valid. If Long.MAX_VALUE, then it's always valid. {{XXX|2**64 is an inappropriate magic value. Review this whole protocol.}}
* Returns: A pair of a new SturdyRef for the indicated object and a persistent [[Runnable]] for cancelling this persistent sturdiness.

{{instance msgdoc|temp|1|<var>obj</var> :[[any]]|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

Produce a temporary [[SturdyRef]] for an object.

Just temp/2 with the optExpirationDate defaulting to forever.

* obj: The object for which a temporary SturdyRef is desired
* Returns: A new temporary SturdyRef for the indicated object

{{instance msgdoc|temp|2|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

Produce a non-cancellable temporary SturdyRef for an object.

A temporary SturdyRef is the oxymoron it seems to be. Like a persistent
SturdyRef, it can be used for offline introductions, or to reconnect
following a partition. However, it cannot survive the crash and revive
of this incarnation of its hosting vat. Typically, it is used only for
ephemeral vats — vats which themselves are never made persistent.

Because temporary SturdyRefs are not used as roots for persistence, the
<code>temp</code> methods accept argument objects which cannot be serialized
for persistence. Conceivably, this even has utility in the context of a
persistent vat.

{{specbycode|identityMgr.makeKnown(<var>obj</var>,<var>optExpirationDate</var>)[0]}}

{{instance msgdoc|onRevival|3|<var>reactor</var> :[[any]], <var>verb</var> :[[String]], <var>args</var> :Tuple<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

Arrange for reactor to eventually be notified as
reactor <- verb(args...)
following future revivals.

Once this notification is no longer needed on further revivals, the
notification action should use the returned persistent [[Runnable]] to
cancel them.

{{XXX|Give rationale for this being (r,v,a) rather than just reactor and run/1.}}

[[Category:CapTP]]

Kevin Reid: copy from javadoc (permission was given)

Kevin Reid — Mon, 10 Aug 2009 01:13:16 GMT

copy from javadoc (permission was given)

←Older revision		Revision as of 01:13, 10 August 2009
Line 1:		Line 1:
-	[[makeSturdyRef]] is used to register objects so that SturdyRefs to them exist. It differs from [[IdentityMgr]] in that it provides ''persistent'' (when used with [[timeMachine]]) registrations.	+	[[makeSturdyRef]], available in the [[privilegedEnv]] is used to register objects so that SturdyRefs to them exist. It differs from [[IdentityMgr]] in that it provides ''persistent'' (when used with [[timeMachine]]) registrations.

-	~~==Protocol==~~	+	<!-- Original javadoc, rewrite -->
		+	"Enables one to make SturdyRefs for objects, even if one is in a distributed
		+	confinement box."

-	~~{{XXX\|MarkM: Assuming you wrote it~~, ~~your permission~~ is ~~requested~~ to ~~copy~~ the ~~doc text~~ from ~~SturdyRefMaker.java~~.}}	+	makeSturdyRef isn't itself Persistent, but it is an exit, so a persistent object holding a persistent
		+	pointer to it will likely revive holding the instance from the new vat incarnation.
		+
		+	==Protocol==

	{{XXX\|Review: Type of expiration date field. Distinguish finite from infinite time.}}		{{XXX\|Review: Type of expiration date field. Distinguish finite from infinite time.}}
Line 9:		Line 14:
	{{instance msgdoc\|tearOffRoots\|2\|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[FlexMap]]}}		{{instance msgdoc\|tearOffRoots\|2\|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[FlexMap]]}}

-	~~{{unspecified message}}~~	+	Uses the "tear-off" technique for establishing private shared state
		+	between two objects.
		+
		+	The "tear-off" tag can only be torn off once, and once it's torn off
		+	it's apparent that it is to all those who try to do so.
		+
		+	In this case, the tearing off is supposed to happen by the [[TimeMachine]]
		+	when it transitions out of the [[TimeMachine#Ephemeral\|Ephemeral]] state. Therefore, if a tearOff
		+	hasn't happened yet, the code here assumes that we're still in the
		+	Ephemeral state and that nothing may be made persistent.
		+
		+	Note: If you want to make something sturdy for purposes of distribution,
		+	but not persistent, use [[IdentityMgr]] or [[#temp/2]] instead.
		+	This requires the [[Introducer]] to be identified, but is independent of the
		+	state of the [[TimeMachine]].

	{{instance msgdoc\|run\|1\|<var>obj</var> :[[any]]\|[[SturdyRef]]}}		{{instance msgdoc\|run\|1\|<var>obj</var> :[[any]]\|[[SturdyRef]]}}

-	~~{{unspecified message}}~~	+	Produce a persistent perpetual [[SturdyRef]] for an object.
		+
		+	Just run/2 with the optExpirationDate defaulting to forever.
		+
		+	* obj: The object for which a SturdyRef is desired
		+	* Returns: A new SturdyRef for the indicated object

	{{instance msgdoc\|run\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[SturdyRef]]}}		{{instance msgdoc\|run\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[SturdyRef]]}}

-	{{~~unspecified message~~}}	+	Produce a non-cancellable persistent SturdyRef for an object.
		+
		+	{{specbycode\|makeSturdyRef.make(obj,optExpirationDate)[0]}}.

	{{instance msgdoc\|vow\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}		{{instance msgdoc\|vow\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

-	~~{{unspecified message}}~~	+	Produce a vow for a persistent perpetual SturdyRef for an object.
		+
		+	Just vow/2 with the optExpirationDate defaulting to forever.
		+
		+	* obj: The object for which a SturdyRef is desired
		+	* Returns: A vow for a new SturdyRef for the indicated object

	{{instance msgdoc\|vow\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}		{{instance msgdoc\|vow\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

-	{{~~unspecified message~~}}	+
		+	Produce a vow for a non-cancellable persistent SturdyRef for an object.
		+
		+	Makes the SturdyRef immediately, but only resolves the vow after the
		+	next time the associated timeMachine is saved; so only committed
		+	SturdyRefs are available to be given out.
		+
		+	{{XXX\|We should extend the behavior of this to allow it to be called
		+	before the introducer is identified or onTheAir, it which case it should
		+	wait for that before internally making the SturdyRef.}}
		+
		+	* obj: The object for which a SturdyRef is desired
		+	* returns: A vow for a new SturdyRef for the indicated object

	{{instance msgdoc\|make\|1\|<var>obj</var> :[[any]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}		{{instance msgdoc\|make\|1\|<var>obj</var> :[[any]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}

-	~~{{unspecified message}}~~	+	optExpirationDate defaults to forever.

	{{instance msgdoc\|make\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}		{{instance msgdoc\|make\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}

-	{{~~unspecified message~~}}	+	Produce a SturdyRef for a persistence-capable object, thereby making it
		+	persistent.
		+
		+	The SturdyRef will designate the object across time and space, at least
		+	until the expiration time, so long as the hosting vat (this vat) is
		+	accessible.
		+
		+	* obj: The object for which a SturdyRef is desired
		+	* optExpirationDate: The date after which the SturdyRef will not longer be guaranteed to be valid. If Long.MAX_VALUE, then it's always valid. {{XXX\|2**64 is an inappropriate magic value. Review this whole protocol.}}
		+	* Returns: A pair of a new SturdyRef for the indicated object and a
		+	persistent [[Runnable]] for cancelling this persistent
		+	sturdiness.
		+

	{{instance msgdoc\|temp\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}		{{instance msgdoc\|temp\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

-	~~{{unspecified message}}~~	+	Produce a temporary [[SturdyRef]] for an object.
		+
		+	Just temp/2 with the optExpirationDate defaulting to forever.
		+
		+	* obj: The object for which a temporary SturdyRef is desired
		+	* Returns: A new temporary SturdyRef for the indicated object

	{{instance msgdoc\|temp\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}		{{instance msgdoc\|temp\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

-	{{~~unspecified message~~}}	+	Produce a non-cancellable temporary SturdyRef for an object.
		+
		+	A temporary SturdyRef is the oxymoron it seems to be. Like a persistent
		+	SturdyRef, it can be used for offline introductions, or to reconnect
		+	following a partition. However, it cannot survive the crash and revive
		+	of this incarnation of its hosting vat. Typically, it is used only for
		+	ephemeral vats — vats which themselves are never made persistent.
		+
		+	Because temporary SturdyRefs are not used as roots for persistence, the
		+	<code>temp</code> methods accept argument objects which cannot be serialized
		+	for persistence. Conceivably, this even has utility in the context of a
		+	persistent vat.
		+
		+	{{specbycode\|identityMgr.makeKnown(<var>obj</var>,<var>optExpirationDate</var>)[0]}}

	{{instance msgdoc\|onRevival\|3\|<var>reactor</var> :[[any]], <var>verb</var> :[[String]], <var>args</var> :Tuple<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}		{{instance msgdoc\|onRevival\|3\|<var>reactor</var> :[[any]], <var>verb</var> :[[String]], <var>args</var> :Tuple<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}

-	~~{{unspecified message}}~~	+	Arrange for reactor to eventually be notified as
		+	reactor <- verb(args...)
		+	following future revivals.
		+
		+	Once this notification is no longer needed on further revivals, the
		+	notification action should use the returned persistent [[Runnable]] to
		+	cancel them.

	{{XXX\|Give rationale for this being (r,v,a) rather than just reactor and run/1.}}		{{XXX\|Give rationale for this being (r,v,a) rather than just reactor and run/1.}}

-	~~{{stub}}~~
	[[Category:CapTP]]		[[Category:CapTP]]

Kevin Reid: wrong arity

Kevin Reid — Sun, 09 Aug 2009 12:56:47 GMT

wrong arity

←Older revision		Revision as of 12:56, 9 August 2009
Line 7:		Line 7:
	{{XXX\|Review: Type of expiration date field. Distinguish finite from infinite time.}}		{{XXX\|Review: Type of expiration date field. Distinguish finite from infinite time.}}

-	{{instance msgdoc\|tearOffRoots\|1\|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[FlexMap]]}}	+	{{instance msgdoc\|tearOffRoots\|2\|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[FlexMap]]}}

	{{unspecified message}}		{{unspecified message}}

Kevin Reid: correct, expand with all msgs

Kevin Reid — Sun, 09 Aug 2009 12:55:05 GMT

correct, expand with all msgs

←Older revision		Revision as of 12:55, 9 August 2009
Line 1:		Line 1:
-	~~the functions~~ makeSturdyRef~~(obj)/1 and makeSturdyRef(obj, expireDate)/2 return an SturdyReference~~ that ~~will persist with the vat~~ when ~~the vats~~ [[timeMachine]] ~~saves it to disk~~.	+	[[makeSturdyRef]] is used to register objects so that SturdyRefs to them exist. It differs from [[IdentityMgr]] in that it provides ''persistent'' (when used with [[timeMachine]]) registrations.

-	~~That means that~~ the ~~sturdyrefs so made will be valid across vat restarts~~.	+	==Protocol==
		+
		+	{{XXX\|MarkM: Assuming you wrote it, your permission is requested to copy the doc text from SturdyRefMaker.java.}}
		+
		+	{{XXX\|Review: Type of expiration date field. Distinguish finite from infinite time.}}
		+
		+	{{instance msgdoc\|tearOffRoots\|1\|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[FlexMap]]}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|run\|1\|<var>obj</var> :[[any]]\|[[SturdyRef]]}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|run\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[SturdyRef]]}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|vow\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|vow\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|make\|1\|<var>obj</var> :[[any]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|make\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|temp\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|temp\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{instance msgdoc\|onRevival\|3\|<var>reactor</var> :[[any]], <var>verb</var> :[[String]], <var>args</var> :Tuple<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}
		+
		+	{{unspecified message}}
		+
		+	{{XXX\|Give rationale for this being (r,v,a) rather than just reactor and run/1.}}

	{{stub}}		{{stub}}
		+	[[Category:CapTP]]

Zarutian: what else to add?

Zarutian — Sun, 09 Aug 2009 02:54:43 GMT

what else to add?

←Older revision		Revision as of 02:54, 9 August 2009
Line 1:		Line 1:
	the functions makeSturdyRef(obj)/1 and makeSturdyRef(obj, expireDate)/2 return an SturdyReference that will persist with the vat when the vats [[timeMachine]] saves it to disk.		the functions makeSturdyRef(obj)/1 and makeSturdyRef(obj, expireDate)/2 return an SturdyReference that will persist with the vat when the vats [[timeMachine]] saves it to disk.
		+
		+	That means that the sturdyrefs so made will be valid across vat restarts.

	{{stub}}		{{stub}}

Zarutian: Page created

Zarutian — Sun, 09 Aug 2009 02:53:13 GMT

Page created

←Older revision		Revision as of 02:53, 9 August 2009
Line 1:		Line 1:
-	[[makeSturdyRef]], ~~available in~~ the ~~[[privilegedEnv]] is used to register objects so that SturdyRefs to them exist. It differs from [[IdentityMgr]] in that it provides ''persistent'' (~~when ~~used with~~ [[timeMachine]]~~) registrations~~.	+	the functions makeSturdyRef(obj)/1 and makeSturdyRef(obj, expireDate)/2 return an SturdyReference that will persist with the vat when the vats [[timeMachine]] saves it to disk.

-	~~<!-- Original javadoc, rewrite -->~~	+	{{stub}}
-	~~"Enables one to make SturdyRefs for objects, even if one is in a distributed~~	+
-	~~confinement box."~~	+
-		+
-	~~makeSturdyRef isn't itself Persistent, but it is an exit, so a persistent object holding a persistent~~	+
-	~~pointer to it will likely revive holding the instance from the new vat incarnation.~~	+
-		+
-	~~==Protocol==~~	+
-		+
-	{{~~XXX\|Review: Type of expiration date field. Distinguish finite from infinite time.~~}}	+
-		+
-	{{instance msgdoc\|tearOffRoots\|2\|<var>optOldRoots</var> :[[nullOk]]<nowiki>[</nowiki>[[FlexMap]]<nowiki>]</nowiki>, <var>optTimeMachine</var> [[nullOk]]<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[FlexMap]]}}	+
-		+
-	~~Uses the "tear-off" technique for establishing private shared state~~	+
-	~~between two objects.~~	+
-		+
-	~~The "tear-off" tag can only be torn off once, and once it's torn off~~	+
-	~~it's apparent that it is to all those who try to do so.~~	+
-		+
-	~~In this case, the tearing off is supposed to happen by the [[TimeMachine]]~~	+
-	~~when it transitions out of the [[TimeMachine#Ephemeral\|Ephemeral]] state. Therefore, if a tearOff~~	+
-	~~hasn't happened yet, the code here assumes that we're still in the~~	+
-	~~Ephemeral state and that nothing may be made persistent.~~	+
-		+
-	~~Note: If you want to make something sturdy for purposes of distribution,~~	+
-	~~but not persistent, use [[IdentityMgr]] or [[#temp/2]] instead.~~	+
-	~~This requires the [[Introducer]] to be identified, but is independent of the~~	+
-	~~state of the [[TimeMachine]].~~	+
-		+
-	~~{{instance msgdoc\|run\|1\|<var>obj</var> :[[any]]\|[[SturdyRef]]}}~~	+
-		+
-	~~Produce a persistent perpetual [[SturdyRef]] for an object.~~	+
-		+
-	~~Just run/2 with the optExpirationDate defaulting to forever.~~	+
-		+
-	* obj: The object for which a SturdyRef is desired	+
-	* Returns: A new SturdyRef for the indicated object	+
-		+
-	~~{{instance msgdoc\|run\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[SturdyRef]]}}~~	+
-		+
-	~~Produce a non-cancellable persistent SturdyRef for an object.~~	+
-		+
-	~~{{specbycode\|makeSturdyRef.make(obj,optExpirationDate)[0]}}.~~	+
-		+
-	~~{{instance msgdoc\|vow\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}~~	+
-		+
-	~~Produce a vow for a persistent perpetual SturdyRef for an object.~~	+
-		+
-	~~Just vow/2 with the optExpirationDate defaulting to forever.~~	+
-		+
-	* obj: The object for which a SturdyRef is desired	+
-	* Returns: A vow for a new SturdyRef for the indicated object	+
-		+
-	~~{{instance msgdoc\|vow\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}~~	+
-		+
-		+
-	~~Produce a vow for a non-cancellable persistent SturdyRef for an object.~~	+
-		+
-	~~Makes the SturdyRef immediately, but only resolves the vow after the~~	+
-	~~next time the associated timeMachine is saved; so only committed~~	+
-	~~SturdyRefs are available to be given out.~~	+
-		+
-	~~{{XXX\|We should extend the behavior of this to allow it to be called~~	+
-	~~before the introducer is identified or onTheAir, it which case it should~~	+
-	~~wait for that before internally making the SturdyRef.}}~~	+
-		+
-	* obj: The object for which a SturdyRef is desired	+
-	* returns: A vow for a new SturdyRef for the indicated object	+
-		+
-	~~{{instance msgdoc\|make\|1\|<var>obj</var> :[[any]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}~~	+
-		+
-	~~optExpirationDate defaults to forever.~~	+
-		+
-	~~{{instance msgdoc\|make\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[Tuple]]<nowiki>[</nowiki>[[SturdyRef]], [[Runnable]]<nowiki>]</nowiki>}}~~	+
-		+
-	~~Produce a SturdyRef for a persistence-capable object, thereby making it~~	+
-	~~persistent.~~	+
-		+
-	~~The SturdyRef will designate the object across time and space, at least~~	+
-	~~until the expiration time, so long as the hosting vat (this vat) is~~	+
-	~~accessible.~~	+
-		+
-	* obj: The object for which a SturdyRef is desired	+
-	* optExpirationDate: The date after which the SturdyRef will not longer be guaranteed to be valid. If Long.MAX_VALUE, then it's always valid. {{XXX\|2**64 is an inappropriate magic value. Review this whole protocol.}}	+
-	* Returns: A pair of a new SturdyRef for the indicated object and a persistent [[Runnable]] for cancelling this persistent sturdiness.	+
-		+
-		+
-	~~{{instance msgdoc\|temp\|1\|<var>obj</var> :[[any]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}~~	+
-		+
-	~~Produce a temporary [[SturdyRef]] for an object.~~	+
-		+
-	~~Just temp/2 with the optExpirationDate defaulting to forever.~~	+
-		+
-	* obj: The object for which a temporary SturdyRef is desired	+
-	* Returns: A new temporary SturdyRef for the indicated object	+
-		+
-	~~{{instance msgdoc\|temp\|2\|<var>obj</var> :[[any]], <var>optExpirationDate</var> :[[int]]\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}~~	+
-		+
-	~~Produce a non-cancellable temporary SturdyRef for an object.~~	+
-		+
-	~~A temporary SturdyRef is the oxymoron it seems to be. Like a persistent~~	+
-	~~SturdyRef, it can be used for offline introductions, or to reconnect~~	+
-	~~following a partition. However, it cannot survive the crash and revive~~	+
-	~~of this incarnation of its hosting vat. Typically, it is used only for~~	+
-	~~ephemeral vats — vats which themselves are never made persistent.~~	+
-		+
-	~~Because temporary SturdyRefs are not used as roots for persistence, the~~	+
-	~~<code>temp</code> methods accept argument objects which cannot be serialized~~	+
-	~~for persistence. Conceivably, this even has utility in the context of a~~	+
-	~~persistent vat.~~	+
-		+
-	~~{{specbycode\|identityMgr.makeKnown(<var>obj</var>,<var>optExpirationDate</var>)[0]}}~~	+
-		+
-	{{instance msgdoc\|onRevival\|3\|<var>reactor</var> :[[any]], <var>verb</var> :[[String]], <var>args</var> :Tuple<nowiki>[</nowiki>[[any]]<nowiki>]</nowiki>\|[[vow]]<nowiki>[</nowiki>[[SturdyRef]]<nowiki>]</nowiki>}}	+
-		+
-	~~Arrange for reactor to eventually be notified as~~	+
-	~~reactor <- verb(args...)~~	+
-	~~following future revivals.~~	+
-		+
-	~~Once this notification is no longer needed on further revivals, the~~	+
-	~~notification action should use the returned persistent [[Runnable]] to~~	+
-	~~cancel them.~~	+
-		+
-	~~{{XXX\|Give rationale for this being (r,v,a) rather than just reactor and run/1.}}~~	+
-		+
-	~~[[Category:CapTP]]~~	+