Object Ref

From Erights

(Difference between revisions)
Jump to: navigation, search
(stub, note missing tests)
(add when* methods from javadoc)
 
Line 5: Line 5:
== Protocol ==
== Protocol ==
-
{{XXX}} specify and test behavior
+
{{XXX|completely specify and test behavior}}
-
[[Category:Incomplete specifications]]
+
 +
{{instance msgdoc|resolution|1|<var>ref</var> :[[any]]|[[any]]}}
 +
 +
Observably, this operation returns <var>ref</var> or something indistinguishable from it. If applicable in the implementation, if <var>ref</var> is a forwarder such as a resolved promise, it will return the referent, and any other such applicable optimizations.
 +
 +
{{instance msgdoc|fulfillment|1|<var>ref</var> :[[any]]|[[any]]}}
 +
 +
Requires that <var>ref</var> is [[fulfilled]].
 +
 +
If <var>ref</var> is
 +
* [[fulfilled]] (resolved and not broken), then <code>Ref.fulfillment(<var>ref</var>)</code> returns <code>[[#resolution/1|Ref.resolution]](<var>ref</var>)</code>.
 +
* a [[promise]] (unresolved), then <code>Ref.fulfillment(<var>ref</var>)</code> throws indicating this. {{XXX|Specify exception type?}}
 +
* [[broken]], then <code>Ref.fulfillment(<var>ref</var>)</code> throws its problem.
 +
 +
{{instance msgdoc|promise|0||[[Tuple]]<nowiki>[</nowiki>[[Promise]], [[LocalResolver]]]}}
 +
 +
{{unspecified message}}
 +
 +
{{instance msgdoc|broken|1|<var>problem</var> :[[Exception]]|[[broken]]}}
 +
 +
{{unspecified message}}
 +
 +
# Regression test
 +
? Ref.broken(null)
 +
# problem: <NullPointerException: Missing problem>
 +
 +
{{instance msgdoc|whenResolved|2|<var>ref</var> :[[any]], <var>reactor</var> :[[OneArgFunc]]|{{sub|[[vow]]|[[any]]}} }}
 +
 +
Used for the when-catch construct {{XXX|add link}}.
 +
 +
If <var>ref</var> never becomes resolved, the reactor is not invoked. Should <var>ref</var> become resolved, <var>reactor</var> will be invoked exactly once. For example, if <var>ref</var> becomes fulfilled and then broken, <var>reactor</var> will hear of exactly one of these events.
 +
 +
Once <var>ref</var> becomes resolved <var>reactor</var> will be invoked with the resolution. Should <var>reactor</var> be invoked with a non-broken value (and therefore a fulfilled value), all earlier messages sent on <var>ref</var> before the whenResolved are guaranteed to have been successfully delivered.
 +
 +
{{instance msgdoc|whenResolvedOnly|2|<var>ref</var> :[[any]], <var>reactor</var> :[[OneArgFunc]]|[[void]]}}
 +
 +
Like whenResolved/2 but without a conventional return result. Use this when you don't care about the return value of <var>reactor</var>.
 +
 +
 +
{{instance msgdoc|whenBroken|2|<var>ref</var> :[[any]], <var>reactor</var> :[[OneArgFunc]]|{{sub|[[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 [http://www.eros-os.org/pipermail/e-lang/2001-August/005638.html here]. Note that, if ref becomes near, it'll never break, so the returned promise will never be resolved!
 +
 +
{{instance msgdoc|whenBrokenOnly|2|<var>ref</var> :[[any]], <var>reactor</var> :[[OneArgFunc]]|[[void]]}}
 +
 +
Like whenBroken/2 but without a conventional return result. Use this when you don't care about the return value of <var>reactor</var>.
 +
 +
[[Category:Incomplete specifications]]
{{stub}}
{{stub}}
[[Category:ELib specification]]
[[Category:ELib specification]]

Latest revision as of 16:58, 28 August 2010

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