MakeSturdyRef

From Erights

(Difference between revisions)
Jump to: navigation, search
(Page created)
m
 
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]], 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.
-
{{stub}}
+
<!-- Original javadoc, rewrite -->
 +
"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]]

Latest revision as of 16:14, 10 August 2009

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.

Contents

Protocol

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

tearOffRoots/2

Signature: tearOffRoots(optOldRoots :nullOk[FlexMap], optTimeMachine nullOk[any]) :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 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.

run/1

Signature: run(obj :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

run/2

Signature: run(obj :any, optExpirationDate :int) :SturdyRef

Produce a non-cancellable persistent SturdyRef for an object.

Equivalent to makeSturdyRef.make(obj,optExpirationDate)[0]..

vow/1

Signature: vow(obj :any) :vow[SturdyRef]

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

vow/2

Signature: vow(obj :any, optExpirationDate :int) :vow[SturdyRef]


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

make/1

Signature: make(obj :any) :Tuple[SturdyRef, Runnable]

optExpirationDate defaults to forever.

make/2

Signature: make(obj :any, optExpirationDate :int) :Tuple[SturdyRef, Runnable]

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.


temp/1

Signature: temp(obj :any) :vow[SturdyRef]

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

temp/2

Signature: temp(obj :any, optExpirationDate :int) :vow[SturdyRef]

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 temp methods accept argument objects which cannot be serialized for persistence. Conceivably, this even has utility in the context of a persistent vat.

Equivalent to identityMgr.makeKnown(obj,optExpirationDate)[0].

onRevival/3

Signature: onRevival(reactor :any, verb :String, args :Tuple[any]) :vow[SturdyRef]

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.

Personal tools
more tools