MakeSturdyRef

From Erights

(Difference between revisions)
Jump to: navigation, search
m
(Page created)
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]]
+

Revision as of 02:53, 9 August 2009

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.

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