edu.rice.cs.util.newjvm
Class AbstractMasterJVM

java.lang.Object
  edu.rice.cs.util.newjvm.AbstractMasterJVM

All Implemented Interfaces:

MasterRemote, Remote

Direct Known Subclasses:

IntegratedMasterSlaveTest.TestMasterJVM, MainJVM

public abstract class AbstractMasterJVM
extends Object
implements MasterRemote

An abstract class implementing the logic to invoke and control, via RMI, a second Java virtual machine. This class is used by subclassing it. (See package documentation for more details.) The state-changing methods of this class consistently block until a precondition for the state change is satisfied — for example, quitSlave() cannot complete until a slave is running. Only one thread may change the state at a time. Thus, clients should be careful to only invoke state-changing methods when they are guaranteed to succeed (only invoking quitSlave(), for example, when it is known to have been matched by a successful invokeSlave invocation).

Version:

$Id: AbstractMasterJVM.java 5246 2010-05-07 19:10:44Z mgricken $

Nested Class Summary

private static class	AbstractMasterJVM.SlaveFactory Loads an instance of the given AbstractSlaveJVM class.
private static class	AbstractMasterJVM.State Synchronization strategy: compare-and-swap guarantees that only one thread enters a STARTING, or QUITTING, or DISPOSED state.

Field Summary

private LazyThunk<MasterRemote>	_masterStub
private StateMonitor<AbstractMasterJVM.State>	_monitor
private SlaveRemote	_slave The slave JVM remote stub (non-null when the state is RUNNING).
private AbstractMasterJVM.SlaveFactory	_slaveFactory

Constructor Summary

protected

AbstractMasterJVM(String slaveClassName) Set up the master JVM object.

Method Summary

private static void	attemptQuit(SlaveRemote slave) Make a best attempt to invoke slave.quit().
void	checkStillAlive() No-op to prove that the master is still alive.
protected void	dispose() Free the resources required for this object to respond to RMI invocations (useful for applications -- such as testing -- that produce a large number of MasterJVMs as a program runs).
protected abstract void	handleSlaveConnected(SlaveRemote newSlave) Callback for when the slave JVM has connected, and the bidirectional communications link has been established.
protected abstract void	handleSlaveQuit(int status) Callback for when the slave JVM has quit.
protected abstract void	handleSlaveWontStart(Exception e) Callback for when the slave JVM fails to either run or respond to SlaveRemote.start(edu.rice.cs.util.newjvm.MasterRemote).
protected void	invokeSlave(JVMBuilder jvmBuilder) Creates and starts the slave JVM.
protected boolean	isDisposed()
protected void	quitSlave() Quits slave JVM.
private void	transition(AbstractMasterJVM.State from, AbstractMasterJVM.State to) Make a thread-safe state transition.

Methods inherited from class java.lang.Object

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

Field Detail

_monitor

private final StateMonitor<AbstractMasterJVM.State> _monitor

_slaveFactory

private final AbstractMasterJVM.SlaveFactory _slaveFactory

_masterStub

private final LazyThunk<MasterRemote> _masterStub

_slave

private volatile SlaveRemote _slave

The slave JVM remote stub (non-null when the state is RUNNING).

Constructor Detail

AbstractMasterJVM

protected AbstractMasterJVM(String slaveClassName)

Set up the master JVM object. Does not start a slave JVM.

Parameters:

slaveClassName - The fully-qualified class name of the class to start up in the second JVM. Must be a subclass of AbstractSlaveJVM.

Method Detail

handleSlaveConnected

protected abstract void handleSlaveConnected(SlaveRemote newSlave)

Callback for when the slave JVM has connected, and the bidirectional communications link has been established. Provides access to the newly-created slave JVM.

handleSlaveQuit

protected abstract void handleSlaveQuit(int status)

Callback for when the slave JVM has quit.

Parameters:

status - The exit code returned by the slave JVM.

handleSlaveWontStart

protected abstract void handleSlaveWontStart(Exception e)

Callback for when the slave JVM fails to either run or respond to SlaveRemote.start(edu.rice.cs.util.newjvm.MasterRemote).

Parameters:

e - Exception that occurred during startup.

invokeSlave

protected final void invokeSlave(JVMBuilder jvmBuilder)

Creates and starts the slave JVM. If the the slave is currently running, waits until it completes. Also waits until the new process has started up and calls one of handleSlaveConnected(edu.rice.cs.util.newjvm.SlaveRemote) or handleSlaveWontStart(java.lang.Exception) before returning.

Parameters:

jvmBuilder - JVMBuilder to use in starting the remote process.

Throws:

IllegalStateException - If this object has been disposed.

quitSlave

protected final void quitSlave()

Quits slave JVM. If a slave is not currently started and running, blocks until that state is reached.

Throws:

IllegalStateException - If this object has been disposed.

attemptQuit

private static void attemptQuit(SlaveRemote slave)

Make a best attempt to invoke slave.quit(). Log an error if it fails.

dispose

protected void dispose()

Free the resources required for this object to respond to RMI invocations (useful for applications -- such as testing -- that produce a large number of MasterJVMs as a program runs). Requires the slave to have quit; blocks until that occurs. After an object has been disposed, it is no longer useful.

transition

private void transition(AbstractMasterJVM.State from,
                        AbstractMasterJVM.State to)

Make a thread-safe state transition. Blocks until the from state is reached and this thread is successful in performing the transition (only one thread can do so at a time). Throws an IllegalStateException if the DISPOSED state is reached first, since there is never a transition out of the disposed state (the alternative is to block permanently).

isDisposed

protected boolean isDisposed()

checkStillAlive

public void checkStillAlive()

No-op to prove that the master is still alive.

Specified by:

checkStillAlive in interface MasterRemote