Object Ref

From Erights

Revision as of 16:58, 28 August 2010 by Kevin Reid (Talk)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

Ref is an object available in the universal environment which provides the basic operations on refs other than call and send.

? Ref
# value: Ref

Contents

Protocol

XXX completely specify and test behavior

resolution/1

Signature: resolution(ref :any) :any

Observably, this operation returns ref or something indistinguishable from it. If applicable in the implementation, if ref is a forwarder such as a resolved promise, it will return the referent, and any other such applicable optimizations.

fulfillment/1

Signature: fulfillment(ref :any) :any

Requires that ref is fulfilled.

If ref is

  • fulfilled (resolved and not broken), then Ref.fulfillment(ref) returns Ref.resolution(ref).
  • a promise (unresolved), then Ref.fulfillment(ref) throws indicating this. XXX Specify exception type?
  • broken, then Ref.fulfillment(ref) throws its problem.

promise/0

Signature: promise() :Tuple[Promise, LocalResolver]

The specification for this message has not been written.

broken/1

Signature: broken(problem :Exception) :broken

The specification for this message has not been written.

# Regression test
? Ref.broken(null)
# problem: <NullPointerException: Missing problem>

whenResolved/2

Signature: whenResolved(ref :any, reactor :OneArgFunc) :vow[any]

Used for the when-catch construct XXX add link.

If ref never becomes resolved, the reactor is not invoked. Should ref become resolved, reactor will be invoked exactly once. For example, if ref becomes fulfilled and then broken, reactor will hear of exactly one of these events.

Once ref becomes resolved reactor will be invoked with the resolution. Should reactor be invoked with a non-broken value (and therefore a fulfilled value), all earlier messages sent on ref before the whenResolved are guaranteed to have been successfully delivered.

whenResolvedOnly/2

Signature: whenResolvedOnly(ref :any, reactor :OneArgFunc) :void

Like whenResolved/2 but without a conventional return result. Use this when you don't care about the return value of reactor.


whenBroken/2

Signature: whenBroken(ref :any, reactor :OneArgFunc) :vow[any]

Should a breakable reference ever become broken, even if it became fulfilled in the meantime, then the reactor is invoked once with a broken reference.

A vat-crossing reference that gets garbage collected before a partition is not broken by that partition, and therefore doesn't need to inform the reactor. Once a reference is logically garbage (unreachable), it may or may not have been collected yet, and so may or may not inform the reactor of partitions that happen after it is garbage.

Returns a promise that will resolve to the outcome of calling the reactor, as explained here. Note that, if ref becomes near, it'll never break, so the returned promise will never be resolved!

whenBrokenOnly/2

Signature: whenBrokenOnly(ref :any, reactor :OneArgFunc) :void

Like whenBroken/2 but without a conventional return result. Use this when you don't care about the return value of reactor.

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