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.



comments?