org.erights.e.elib.ref
Class FarRef

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

All Implemented Interfaces:

Amplifiable, Callable

class FarRef

extends Proxy

A FarRef is a Proxy intended to be a Resolved Ref to a particular PassByProxy object in a remote Vat.

A FarRef starts out EVENTUAL but may become BROKEN. However, it continues to have whatever settled identity it was born with, and so may be used as a key in EMaps (hashtables). Once a FarRef becomes BROKEN, it severs its connection with its handler. A FarRef is an HONORARY Selfless object (since it's not transparent -- it encapsulates its myIdentity).

Author:

Mark S. Miller

Field Summary

(package private) Object	myIdentity My settled identity is according to .equals() on this settled object.
(package private) ProxyHandler	myOptHandler While I'm handled, I delegate many of my decisions to my handler.
(package private) Ref	myOptTarget Once I'm not handled, I'm resolved to myOptTarget

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

BROKEN, EVENTUAL, NEAR, TheViciousRef

Constructor Summary

(package private)

FarRef(Object identity, ProxyHandler handler)

Method Summary

Object	callAll(String verb, Object[] args) Suppressed: Use E.callAll(obj, verb, args) rather than obj.callAll(verb, args).
(package private) void	commit() ignored
boolean	equals(Object other) As an HONORARY Selfless object, my .equals() and .hashCode() determine sameness.
ProxyHandler	getOptProxyHandler(Class handlerClass) If this is a handled Proxy whose handler is an instance of handlerClass, then return that handler; else null.
int	hashCode() As an HONORARY Selfless object, my .equals() and .hashCode() determine sameness.
boolean	isResolved() Suppressed:
Throwable	optProblem() If handled, return null; else return the target's problem.
SealedBox	optSealedDispatch(Brand brand) If handled, ask our handler; else delegate to our target.
(package private) Ref	resolutionRef() If this proxy is still being handled, return this; else return whatever it's been shortened to.
Ref	sendAll(String verb, Object[] args) Suppressed: Use E.sendAll(obj, verb, args) rather than obj.sendAll(verb, args).
Throwable	sendAllOnly(String verb, Object[] args) Suppressed: Use E.sendAllOnly(obj, verb, args) rather than obj.sendAllOnly(verb, args).
(package private) void	setTarget(Ref newTarget) To set me is to commit me
String	state() If handled, returns EVENTUAL; else returns the target's state().

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

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

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

myIdentity

final Object myIdentity

My settled identity is according to .equals() on this settled object.

myOptHandler

ProxyHandler myOptHandler

While I'm handled, I delegate many of my decisions to my handler.

myOptTarget

Ref myOptTarget

Once I'm not handled, I'm resolved to myOptTarget

Constructor Detail

FarRef

FarRef(Object identity,
       ProxyHandler handler)

Method Detail

equals

public boolean equals(Object other)

As an HONORARY Selfless object, my .equals() and .hashCode() determine sameness.

NOTE: Uses myIdentity's .equals(), which is safe, as myIdentity must be an honorary Selfless object.

Overrides:

equals in class Object

Parameters:

other - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

See Also:

Object.hashCode(), java.util.Hashtable

hashCode

public int hashCode()

As an HONORARY Selfless object, my .equals() and .hashCode() determine sameness.

NOTE: Uses myIdentity's .hashCode(), which is safe, as myIdentity must be an honorary Selfless object.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

java.lang.Object#equals(java.lang.Object), java.util.Hashtable

isResolved

public boolean isResolved()

Description copied from class: Ref

Suppressed:

Specified by:

isResolved in class Ref

setTarget

void setTarget(Ref newTarget)

To set me is to commit me

Specified by:

setTarget in class Ref

optSealedDispatch

public SealedBox optSealedDispatch(Brand brand)

If handled, ask our handler; else delegate to our target.

Specified by:

optSealedDispatch in interface Amplifiable

Overrides:

optSealedDispatch in class Ref

getOptProxyHandler

public ProxyHandler getOptProxyHandler(Class handlerClass)

If this is a handled Proxy whose handler is an instance of handlerClass, then return that handler; else null.

All implementations of getOptProxyHandler/1 must be thread safe, in order for BootRefHandler.getOptBootRefHandler/1 to be thread safe: myOptHandler only makes one transition from non-null to null. This implementation samples it once, and then proceeds with the possibly slightly stale sample.

Overrides:

getOptProxyHandler in class Ref

optProblem

public Throwable optProblem()

If handled, return null; else return the target's problem.

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

See Also:

Ref.optProblem(Object)

resolutionRef

Ref resolutionRef()

If this proxy is still being handled, return this; else return whatever it's been shortened to.

All implementations of resolutionRef/0 must be thread safe, in order for Ref.resolution/0 to be thread safe: If resolutionRef/0 is called from another thread while this proxy is in the middle of being shortened, then resolutionRef/0 must return either this or what this proxy is being shortened to.

XXX Although the implementation doesn't synchronize, it is inductively thread safe given a simple memory model. Is it safe in Java's complex memory model? Do we care -- are any Java implementations not faithful to the simple memory model?

Specified by:

resolutionRef in class Ref

state

public String state()

If handled, returns EVENTUAL; else returns the target's state().

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

Overrides:

state in class Ref

See Also:

Ref.state(Object)

callAll

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

Description copied from class: Ref

Suppressed: Use E.callAll(obj, verb, args) rather than obj.callAll(verb, args).

Specified by:

callAll in interface Callable

Specified by:

callAll in class Ref

sendAll

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

Description copied from class: Ref

Suppressed: Use E.sendAll(obj, verb, args) rather than obj.sendAll(verb, args).

Specified by:

sendAll in class Ref

sendAllOnly

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

Description copied from class: Ref

Suppressed: Use E.sendAllOnly(obj, verb, args) rather than obj.sendAllOnly(verb, args).

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.

commit

void commit()

ignored

Specified by:

commit in class Ref