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:

• The boot-comm-system can only be used to communicate with vats within the same jvm (or host OS address space).
• Communications happen by pointer manipulation, not serialization, so the only PassByConstruction arguments that may be passed or returned as results are those that are DeepPassByCopy.

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:

• If src and dest are the same, then returns arg.
• If arg is DeepPassByCopy or a broken reference, then it can be invoked from any vat, so we pass it as is.
• If it's a BootShuttle, then we pass it as is. Be careful!
• If it's PassByProxy, then we gotta wrap it in a boot-ref for use in the dest vat, and return that.
• If it's already a boot-ref, then we gotta determine which vat is it's target's vat. If it's target's vat is
  • the dest, then return its target.
  • some other vat, then we re-wrap it in a fresh boot-ref
  • (it would be an error for it to be the src vat)
• If it's a non-boot-ref eventual reference, then we wrap it in a boot-ref and return that, but we also send a __whenMoreResolved message to the eventual reference in the src vat, where the argument is a boot-ref on a Redirector on the returned boot-ref.
• In all other cases, an exception is thrown.

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