m |
|
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]]
| + | |
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.