MakeSturdyRef

From Erights

(Difference between revisions)
Jump to: navigation, search
m (wrong arity)
m
 
(3 intermediate revisions not shown)
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]]

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