org.erights.e.elib.ref
Class BufferingRef

java.lang.Object
  |
  +--org.erights.e.elib.ref.Ref
        |
        +--org.erights.e.elib.ref.BufferingRef

All Implemented Interfaces:

Amplifiable, Callable

class BufferingRef

extends Ref

A BufferingRef, although a proper Ref, is intended for use (by composition) only within other Ref implementations. A BufferingRef is forever EVENTUAL, and simply stores all Messages asynchronously sent to it in a buffer, a FlexList of Messages, acting in the role of its resolver. In other word, a buffering promise consists two facets: a BufferingRef and the FlexList into stores the incoming messages. The static method deliverAll() is provided for use on the buffer, effectively acting as a resolver method.

A BufferingRef points at its buffer weakly, since if no one else still has ahold of the buffer, there's no reason to keep it. In this case, incoming messages are silently ignored with no externally visible effect. Therefore, even though the non-determinism of GC timing is visible within the implementation of a buffering promise, it presents its clients with a fully deterministic contract.

Author:

Mark S. Miller

Field Summary

private java.lang.ref.WeakReference

myBuf

Fields inherited from class org.erights.e.elib.ref.Ref

BROKEN, EVENTUAL, NEAR, TheViciousRef

Constructor Summary

(package private)

BufferingRef(FlexList resolver)

Method Summary

Object	callAll(String verb, Object[] args) Complains.
(package private) void	commit() Used by a resolvers to turn off switchability, and thereby make this Ref equivalent to its current target.
(package private) static int	deliverAll(FlexList buf, Object target) Asyncronously send all the messages accumulated so far to the target, forget them (so future deliverAll()s won't send them), and return the count of how many messages this is.
boolean	isResolved() Suppressed:
Throwable	optProblem() Returns null.
(package private) Ref	resolutionRef() Returns this.
Ref	sendAll(String verb, Object[] args) Stores the message
Throwable	sendAllOnly(String verb, Object[] args) Stores the message.
void	sendMsg(Message msg) Suppressed: Eventually sends a packaged message to this object.
(package private) void	setTarget(Ref newTarget) Used by a resolvers to change the target.
String	state() Returns EVENTUAL.

Methods inherited from class org.erights.e.elib.ref.Ref

broken, disconnected, getAllegedType, getOptProxyHandler, GetRefMaker, ignore, isBroken, isDeepFrozen, isDeepPassByCopy, isEventual, isFar, isNear, isPassByProxy, isPBC, isPersistent, isResolved, isSameEver, isSelfish, isSelfless, isSettled, makeBufferingPromise, makeSwitchablePromise, optBroken, optProblem, optSealedDispatch, optSealedDispatch, optShorten, promise, resolution, resolution, respondsTo, state, toCallable, toRef, toString, whenBroken, whenBrokenOnly, whenResolved, whenResolvedOnly

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

myBuf

private final java.lang.ref.WeakReference myBuf

Constructor Detail

BufferingRef

BufferingRef(FlexList resolver)

Method Detail

optProblem

public Throwable optProblem()

Returns null.

All implementations of optProblem/0 must be thread safe, in order for Ref.state/0 to be thread safe.

Specified by:

optProblem in class Ref

Returns:

null

See Also:

Ref.optProblem(Object)

resolutionRef

Ref resolutionRef()

Returns this.

All implementations of resolutionRef/0 must be thread safe, in order for Ref.resolution/0 to be thread safe.

Specified by:

resolutionRef in class Ref

Returns:

this.

state

public String state()

Returns EVENTUAL.

All implementations of state/0 must be thread safe, in order for Ref.isNear/1 to be thread safe.

Overrides:

state in class Ref

Returns:

EVENTUAL

See Also:

Ref.state(Object)

callAll

public Object callAll(String verb,
                      Object[] args)

Complains.

Specified by:

callAll in interface Callable

Specified by:

callAll in class Ref

sendMsg

public void sendMsg(Message msg)

Description copied from class: Ref

Suppressed: Eventually sends a packaged message to this object.

To the client, this has the same semantics as Ref.sendAll(java.lang.String, java.lang.Object[]) or Ref.sendAllOnly(java.lang.String, java.lang.Object[]), and the default implementation here in Ref just delegates to these. However, those subclasses that can reuse the Message should do so as a nice optimization, and to preserve the SendingContext info captured in msg for causality tracing and debugging.

XXX SECURITY ALERT, No longer true:
This is package scope, since only trusted code is assumed to not resuse a Resolver so as to break distributed transparency. (This safeguard isn't crucial, and isn't even a big deal, but is nice.)

Overrides:

sendMsg in class Ref

sendAll

public Ref sendAll(String verb,
                   Object[] args)

Stores the message

Specified by:

sendAll in class Ref

Returns:

a promise for the result

sendAllOnly

public Throwable sendAllOnly(String verb,
                             Object[] args)

Stores the message.

Specified by:

sendAllOnly in class Ref

Returns:

Why wasn't this event queued? It isn't queued if this vat or comm connection is shut down, in which case the returned problem explains why. If null is returned, then the event was queued, though it may still not arrive.

isResolved

public boolean isResolved()

Description copied from class: Ref

Suppressed:

Specified by:

isResolved in class Ref

setTarget

void setTarget(Ref newTarget)

Description copied from class: Ref

Used by a resolvers to change the target. If newTarget is equivalent to this Ref, then this Ref becomes broken by a ViciousCycleException.

Specified by:

setTarget in class Ref

commit

void commit()

Description copied from class: Ref

Used by a resolvers to turn off switchability, and thereby make this Ref equivalent to its current target.

If the current target is already equivalent to this Ref, then this Ref becomes broken by a ViciousCycleException.

Specified by:

commit in class Ref

deliverAll

static int deliverAll(FlexList buf,
                      Object target)

Asyncronously send all the messages accumulated so far to the target, forget them (so future deliverAll()s won't send them), and return the count of how many messages this is.