autohit.vm
Interface VMProcess

All Known Implementing Classes:

VMProcessAutomat

public interface VMProcess

This defines the interface to a process controller.

BE SURE to .init() this controller BEFORE any other threads access its methods (particularly execute()). Some implementations my be bases on Threads. Be sure to .start() after init() Failure to heed this warning COULD result in a race condition... :-)

 There are four "commands" to a process controller:
 - PAUSE will hold execution
 - RESUME will restart execution
 - STOP will stop execution of the VM and dump it
 - KILL will stop the execution and let this process die!
 

Version:

1.0 Version History EPG - New - 24Jul03

Method Summary

boolean	execute(VM aVM) Load and Execute a VM.
int	getPID() Get's the PID for this process
java.lang.String	getRootProgram() Get's root program
int	getState() A simple request for state.
SystemContext	getSystemContext() Get my system context.
void	init(SystemContext sctx, int setpid) Initialize the process controller.
void	joinIt() Join the process
boolean	kill() Kill this context.
java.lang.Object	processAttribute(java.lang.String name) Get a registered process attribute.
void	run() Run the process.
void	start() Run the process.
int	verifyState() Verify the state of the VM.
boolean	vmPause() Pause the vm.
boolean	vmResume() Resume the vm.
boolean	vmStop() Stop the vm.

Method Detail

init

public void init(SystemContext sctx,
                 int setpid)
          throws VMException

Initialize the process controller. It takes an immutable SystemContext.

Parameters:

sctx - a ready SystemContext. This will be fed to all controlled processes.

setpid - the pid

Throws:

VMException - is the process goes bad

See Also:

VM

execute

public boolean execute(VM aVM)

Load and Execute a VM. If a VM is already running, it will return false. Otherwise, it will return true. Otherwise, it will load it and give the greenlight to the VM thread.

This method can be called by any thread. It will clear the request flags.

Parameters:

aVM - A fully implimented derived-class of VM.

Returns:

true if successful and execution begun, false if another VM is already running or there is an error.

See Also:

VM

vmPause

public boolean vmPause()

Pause the vm. This may be called by another thread. As with vmResume() and vmStop(), it posts a request to the VMContext. The context will not heed the request until the current VM.execute() is complete and the context has a chance to check for these requests.

There is no rendezvous; the method will not block. All successive requests count as the same request until the context services it. There is no guarentee on the timing of the service. The Context will not check for requests until AFTER the current instruction is complete. So, if the vm is executing a long wait instruction, it could indeed be some time before the request is serviced.

If you need to make sure that the request worked, then use the verifyState() method to get the definative state of the VM/Context.

As for the return value, "success" merely means that the request was successfully posted and not that the action was completed.

One last thaught: this is not a robust OS implimentation of a thread context. You might want to restrict calls to vmPause() and vmResume() to a single external thread. Multiple threads might get confused if they don't cooperate...

Returns:

true is successful. false if no vm is running or it is already paused.

See Also:

VM

vmResume

public boolean vmResume()

Resume the vm.

See the notes for the pause() method.

Returns:

true is successful. false if no vm is paused or it is already running.

See Also:

VM

vmStop

public boolean vmStop()

Stop the vm. This will kill it permanently, so be careful.

See the notes for the pause() method.

Returns:

true is successful. false if no vm is running or paused.

See Also:

VM

getPID

public int getPID()

Get's the PID for this process

Returns:

pid

getRootProgram

public java.lang.String getRootProgram()

Get's root program

Returns:

string name of the root program

kill

public boolean kill()

Kill this context. It is irrevocable as it will interrupt the Thread. If you want to request the program to stop, call vmStop();

See the notes for the pause() method.

Returns:

always returns true.

See Also:

VM

verifyState

public int verifyState()

Verify the state of the VM. It will report a VM state value as defined in the VM class--VM.State_*. This will be the authorative state, as this method blocks until the VM has chance to clear requests and unblock it.

(And, never EVER call this method from within THIS thread. You'll almost certainly deadlock it.)

The following describes each state:

         STATE_NEW          = VM is loaded bu not started
         STATE_RUNNING      = VM is actively running.
         STATE_PAUSED       = VM is paused.
         STATE_DONE         = VM finished execution.
                              This is rare, as the VM will
                              be automatically unloaded when
                              finished.
         STATE_NO_VM        = No VM is loaded into this context.
  

Returns:

a VM.State_* value.

See Also:

VM

getState

public int getState()

A simple request for state. It may or not be stale be the time the calling thread gets it. If you msut have THE AUTHORATIVE state, then call verifyState()

Returns:

a VM.State_* value.

See Also:

VM

getSystemContext

public SystemContext getSystemContext()

Get my system context.

Returns:

a SystemContext

See Also:

VM

processAttribute

public java.lang.Object processAttribute(java.lang.String name)

Get a registered process attribute.

Returns:

an object that matches the name

See Also:

VM

run

public void run()

Run the process.

start

public void start()

Run the process.

joinIt

public void joinIt()

Join the process