edu.mit.csail.sdg.alloy4
Class WorkerEngine

java.lang.Object
  edu.mit.csail.sdg.alloy4.WorkerEngine

public final class WorkerEngine
extends java.lang.Object

This class allows you to execute tasks in a subprocess, and receive its outputs via callback.

By executing the task in a subprocess, we can always terminate a runaway task explicitly by calling stop(), and we can control how much memory and stack space to give to the subprocess.

Only one task may execute concurrently at any given time; if you try to issue a new task when the previous task hasn't finished, then you will get an IOException.

As long as the subprocess hasn't terminated either due to crashing or due to user calling stop(), then the same subprocess is reused to execute each subsequent task; however, if the subprocess crashed, the crash will be reported to the parent process via callback, and if we try to execute another task, then a new subprocess will be spawned automatically.

Nested Class Summary

static interface	WorkerEngine.WorkerCallback This defines an interface for receiving results from a subprocess.
static interface	WorkerEngine.WorkerTask This defines an interface for performing tasks in a subprocess.

Method Summary

static boolean	isBusy() This returns true iff the subprocess is still busy processing the last task.
static void	main(java.lang.String[] args) This is the entry point for the sub JVM.
static void	run(WorkerEngine.WorkerTask task, int newmem, int newstack, java.lang.String jniPath, java.lang.String classPath, WorkerEngine.WorkerCallback callback) This issues a new task to the subprocess; if subprocess hasn't been constructed yet or has terminated abnormally, this method will launch a new subprocess.
static void	runLocally(WorkerEngine.WorkerTask task, WorkerEngine.WorkerCallback callback) This executes a task using the current thread.
static void	stop() This terminates the subprocess, and prevent any further results from reaching the parent's callback handler.

Methods inherited from class java.lang.Object

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

Method Detail

stop

public static void stop()

This terminates the subprocess, and prevent any further results from reaching the parent's callback handler.

isBusy

public static boolean isBusy()

This returns true iff the subprocess is still busy processing the last task.

runLocally

public static void runLocally(WorkerEngine.WorkerTask task,
                              WorkerEngine.WorkerCallback callback)
                       throws java.lang.Exception

This executes a task using the current thread.

Parameters:

task - - the task that we want to execute

callback - - the handler that will receive outputs from the task

Throws:

java.io.IOException - - if a previous task is still busy executing

java.lang.Exception

run

public static void run(WorkerEngine.WorkerTask task,
                       int newmem,
                       int newstack,
                       java.lang.String jniPath,
                       java.lang.String classPath,
                       WorkerEngine.WorkerCallback callback)
                throws java.io.IOException

This issues a new task to the subprocess; if subprocess hasn't been constructed yet or has terminated abnormally, this method will launch a new subprocess.

Parameters:

task - - the task that we want the subprocess to execute

newmem - - the amount of memory (in megabytes) we want the subprocess to have (if the subproces has not terminated, then this parameter is ignored)

newstack - - the amount of stack (in kilobytes) we want the subprocess to have (if the subproces has not terminated, then this parameter is ignored)

jniPath - - if nonnull and nonempty, then it specifies the subprocess's default JNI library location

classPath - - if nonnull and nonempty, then it specifies the subprocess's default CLASSPATH, else we'll use System.getProperty("java.class.path")

callback - - the handler that will receive outputs from the task

Throws:

java.io.IOException - - if a previous task is still busy executing

java.io.IOException - - if an error occurred in launching a sub JVM or talking to it

main

public static void main(java.lang.String[] args)

This is the entry point for the sub JVM.

Behavior is very simple: it reads a WorkerTask object from System.in, then execute it, then read another... If any error occurred, or if it's disconnected from the parent process's pipe, it then terminates itself (since we assume the parent process will notice it and react accordingly)