MakeSturdyRef

From Erights

Jump to: navigation, search

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