org.erights.e.elib.vat
Class BootRefHandler

java.lang.Object
  |
  +--org.erights.e.elib.vat.BootRefHandler
All Implemented Interfaces:
ProxyHandler

class BootRefHandler
extends Object
implements ProxyHandler

There is one boot-comm-system per JVM, and all boot-refs (all Refs handled by a BootRefHandler) are part of that one comm system.

The boot-comm-system differs from normal inter-vat comm systems (like CapTP) in the following ways:

When PassByProxy objects are passed between vats by the boot-comm-system, this is done by wrapping or unwrapping them in a BootRefHandler.

Author:
Mark S. Miller

Field Summary
private  boolean myFreshFlag
          Flag to remember whether any E-level messages have been sent over me.
private  ProxyResolver myResolver
          The Resolver of our Proxy, which also revives the Proxy on demand.
(package private)  Object myTarget
           
(package private)  Vat myTargetsVat
          An invocation of a boot-ref will cause an invocation of myTarget in myTargetsVat.
private static Sealer OurSealer
          So that the boot-comm-system can recognize itself.
(package private) static Unsealer OurUnsealer
          So that the boot-comm-system can recognize itself.
 
Constructor Summary
(package private) BootRefHandler(Vat targetsVat, Object target)
          In order to make an EVENTUAL reference to target which will queue messages in targetsVat for delivery to target.
 
Method Summary
private static BootRefHandler getOptBootRefHandler(Object ref)
          If 'ref' is a boot-ref, get its BootRefHandler.
 SealedBox handleOptSealedDispatch(Brand brand)
          Enabled: How should my ref respond to an __optSealedDispatch request?
 void handleResolution(Object newTarget)
          Enabled: My Ref no longer needs me, as it's become equivalent to newTarget.
 Ref handleSendAll(String verb, Object[] args)
          Queues the send in myTargetsVat.
 void handleSendAllOnly(String verb, Object[] args)
          Queues the send in myTargetsVat.
 boolean isFresh()
          Enabled: A reference is fresh if it's redirection doesn't need to be delayed.
private  Object packageArg(Object arg, Vat src, Vat dest, Vat currentVat)
          Given that arg is an object in the src vat (ie, an object that would be safe to invoke in the src vat), then return a ref to it packaged for use in the dest vat.
private  Object[] packageArgs(Object[] args)
          Given that args is packaged for use in the current vat, return a corresponding list of args packaged for use in myTargetsVat.
 void reactToGC()
          Enabled: One of my Refs was GCed, and I have no current Ref.
 boolean sameConnection(Object other)
          Enabled: Are 'other' and the remote reference handled by 'this' part of the same comm system, and do they both connect to the same remote vat?
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OurSealer

private static final Sealer OurSealer
So that the boot-comm-system can recognize itself.


OurUnsealer

static final Unsealer OurUnsealer
So that the boot-comm-system can recognize itself.


myTargetsVat

final Vat myTargetsVat
An invocation of a boot-ref will cause an invocation of myTarget in myTargetsVat.


myTarget

final Object myTarget

myResolver

private final ProxyResolver myResolver
The Resolver of our Proxy, which also revives the Proxy on demand.


myFreshFlag

private boolean myFreshFlag
Flag to remember whether any E-level messages have been sent over me.

Constructor Detail

BootRefHandler

BootRefHandler(Vat targetsVat,
               Object target)
In order to make an EVENTUAL reference to target which will queue messages in targetsVat for delivery to target.

It must be safe to invoke target in targetsVat

Method Detail

handleOptSealedDispatch

public SealedBox handleOptSealedDispatch(Brand brand)
Description copied from interface: ProxyHandler
Enabled: How should my ref respond to an __optSealedDispatch request?

Specified by:
handleOptSealedDispatch in interface ProxyHandler

getOptBootRefHandler

private static BootRefHandler getOptBootRefHandler(Object ref)
If 'ref' is a boot-ref, get its BootRefHandler.

This is like

    ProxyResolver.getOptProxyHandler(org.erights.e.elib.sealing.Unsealer, java.lang.Object)(OurUnsealer, ref)
except that it's thread-safe.

getOptBootRefHandler/1 must be thread safe, in order for BootRefHandler.packageArg/4 to be thread safe: Callers of this should keep in mind that ref may be shortened after the handler is gotten but before these callers use it. If they access only final fields of the handler in a thread safe way, then everything should be fine.


packageArg

private Object packageArg(Object arg,
                          Vat src,
                          Vat dest,
                          Vat currentVat)
Given that arg is an object in the src vat (ie, an object that would be safe to invoke in the src vat), then return a ref to it packaged for use in the dest vat.

By cases:

Parameters:
arg - The reference to be packaged.
src - The vat that 'arg' is valid within.
dest - The vat the return result needs to be valid within.
currentVat - The vat within which we're currently executing, which may be src, dest, or a third introducing vat (Alice). This is used to resolve race conditions.

packageArgs

private Object[] packageArgs(Object[] args)
Given that args is packaged for use in the current vat, return a corresponding list of args packaged for use in myTargetsVat.


handleSendAllOnly

public void handleSendAllOnly(String verb,
                              Object[] args)
Queues the send in myTargetsVat.

Specified by:
handleSendAllOnly in interface ProxyHandler
Parameters:
args - Assumed to be packaged for use in the current vat.

handleSendAll

public Ref handleSendAll(String verb,
                         Object[] args)
Queues the send in myTargetsVat.

Specified by:
handleSendAll in interface ProxyHandler
Parameters:
args - Assumed to be packaged for use in the current vat.
Returns:
the promise for the result packaged for use in the current vat.

handleResolution

public void handleResolution(Object newTarget)
Description copied from interface: ProxyHandler
Enabled: My Ref no longer needs me, as it's become equivalent to newTarget.

Specified by:
handleResolution in interface ProxyHandler

reactToGC

public void reactToGC()
Description copied from interface: ProxyHandler
Enabled: One of my Refs was GCed, and I have no current Ref.

Specified by:
reactToGC in interface ProxyHandler

isFresh

public boolean isFresh()
Description copied from interface: ProxyHandler
Enabled: A reference is fresh if it's redirection doesn't need to be delayed.

A resolved reference doesn't get redirected (except to be smashed), and so is always fresh. A remote promise is fresh if it hasn't been used. A remote promise over which messages have already been sent is not fresh. (Hypothetically, if we know that none of these remain in the air -- that all of them have arrived -- then we could consider the remote promise to be fresh again. This optimization is not currently implemented.)

Specified by:
isFresh in interface ProxyHandler

sameConnection

public boolean sameConnection(Object other)
Description copied from interface: ProxyHandler
Enabled: Are 'other' and the remote reference handled by 'this' part of the same comm system, and do they both connect to the same remote vat?

Specified by:
sameConnection in interface ProxyHandler


comments?