edu.rice.cs.plt.concurrent
Class ConcurrentUtil

java.lang.Object
  edu.rice.cs.plt.concurrent.ConcurrentUtil

public final class ConcurrentUtil
extends Object

Utility methods for executing code in concurrent threads or processes.

Field Summary

static Executor	DIRECT_EXECUTOR A trivial Executor that simply runs each task directly.
static Runnable1<Long>	SLEEPING_RUNNABLE A runnable that simply sleeps for the specified amount of time (milliseconds), or until an interrupt occurs.
static Executor	THREAD_EXECUTOR A simple Executor that creates a new thread for each task; threads are identified by the name THREAD_EXECUTOR-n for some n.
static Runnable1<Long>	WORKING_RUNNABLE A runnable that performs useless computation for the specified amount of time (milliseconds).

Method Summary

static <T> Callable<T>	asCallable(Thunk<? extends T> thunk) Wrap a thunk in a Callable interface.
static <T> TaskController<T>	asTaskController(Future<? extends T> future) Wrap a Future in a TaskController interface (which is also a Thunk).
static <T> TaskController<T>	asTaskController(Thunk<? extends Future<? extends T>> futureThunk) Wrap a Future produced by a Thunk in a TaskController interface (which is also a Thunk).
static <I,R> IncrementalTaskController<I,R>	computeInProcess(IncrementalTask<? extends I,? extends R> task) Execute the given task in a separate process and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeInProcess(IncrementalTask<? extends I,? extends R> task, boolean start) Execute the given task in a separate process and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeInProcess(IncrementalTask<? extends I,? extends R> task, JVMBuilder jvmBuilder) Execute the given task in a separate process and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeInProcess(IncrementalTask<? extends I,? extends R> task, JVMBuilder jvmBuilder, boolean start) Execute the given task in a separate process and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeInProcess(IncrementalTask<? extends I,? extends R> task, JVMBuilder jvmBuilder, boolean start, boolean ignoreIntermediate) Execute the given task in a separate process and provide access to its result.
static <R> TaskController<R>	computeInProcess(Thunk<? extends R> task) Execute the given task in a separate process and provide access to its result.
static <R> TaskController<R>	computeInProcess(Thunk<? extends R> task, boolean start) Execute the given task in a separate process and provide access to its result.
static <R> TaskController<R>	computeInProcess(Thunk<? extends R> task, JVMBuilder jvmBuilder) Execute the given task in a separate process and provide access to its result.
static <R> TaskController<R>	computeInProcess(Thunk<? extends R> task, JVMBuilder jvmBuilder, boolean start) Execute the given task in a separate process and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeInThread(IncrementalTask<? extends I,? extends R> task) Execute the given task in a separate thread, and provide access to its results.
static <I,R> IncrementalTaskController<I,R>	computeInThread(IncrementalTask<? extends I,? extends R> task, boolean start) Execute the given task in a separate thread, and provide access to its results.
static <I,R> IncrementalTaskController<I,R>	computeInThread(IncrementalTask<? extends I,? extends R> task, boolean start, boolean ignoreIntermediate) Execute the given task in a separate thread, and provide access to its results.
static <R> TaskController<R>	computeInThread(Thunk<? extends R> task) Execute the given task in a separate thread, and provide access to its result.
static <R> TaskController<R>	computeInThread(Thunk<? extends R> task, boolean start) Execute the given task in a separate thread, and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeWithExecutor(IncrementalTask<? extends I,? extends R> task, Executor exec) Execute the given task with exec and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeWithExecutor(IncrementalTask<? extends I,? extends R> task, Executor exec, boolean start) Execute the given task with exec and provide access to its result.
static <I,R> IncrementalTaskController<I,R>	computeWithExecutor(IncrementalTask<? extends I,? extends R> task, Executor exec, boolean start, boolean ignoreIntermediate) Execute the given task with exec and provide access to its result.
static <R> TaskController<R>	computeWithExecutor(Thunk<? extends R> task, Executor exec) Execute the given task with exec and provide access to its result.
static <R> TaskController<R>	computeWithExecutor(Thunk<? extends R> task, Executor exec, boolean start) Execute the given task with exec and provide access to its result.
static Thread	copyProcessErr(Process p, OutputStream err) Create a thread that will continually copy the contents of the given process's error output to another output stream.
static Thread	copyProcessErr(Process p, OutputStream err, boolean close) Create a thread that will continually copy the contents of the given process's error output to another output stream.
static Thread	copyProcessOut(Process p, OutputStream out) Create a thread that will continually copy the contents of the given process's standard output to another output stream.
static Thread	copyProcessOut(Process p, OutputStream out, boolean close) Create a thread that will continually copy the contents of the given process's standard output to another output stream.
static void	copyProcessOutput(Process p, OutputStream out, OutputStream err) Create two threads to continually copy the contents of the given process's output and error streams to the given destinations.
static Thread	discardProcessErr(Process p) Create a thread that will continually discard the contents of the given process's standard output.
static Thread	discardProcessOut(Process p) Create a thread that will continually discard the contents of the given process's standard output.
static void	discardProcessOutput(Process p) Create two threads to continually discard the contents of the given process's output and error streams.
static Remote	exportInProcess(Thunk<? extends Remote> factory) Export the given RMI object in a new process and return the exported stub.
static Remote	exportInProcess(Thunk<? extends Remote> factory, JVMBuilder jvmBuilder) Export the given RMI object in a new process and return the exported stub.
static Remote	exportInProcess(Thunk<? extends Remote> factory, JVMBuilder jvmBuilder, Runnable1<? super Process> onExit) Export the given RMI object in a new process and return the exported stub.
static long	futureTimeMillis(long time, TimeUnit unit) Get the expected value of System.currentTimeMillis() after the given period of time has passed.
static long	futureTimeNanos(long time, TimeUnit unit) Get the expected value of System.nanoTime() after the given period has passed.
static Properties	getProperties(String... prefixes) Get a subset of the system properties for names that match at least one of the given prefixes.
static Map<String,String>	getPropertiesAsMap(String... prefixes) Get a subset of the system properties for names that match at least one of the given prefixes.
static void	onProcessExit(Process p, Runnable1<? super Process> listener) Create a daemon thread that will invoke Process.waitFor() on the given process, then run the given listener.
static TaskController<String>	processErrAsString(Process p) Create a task providing access to the given process's error output as a string.
static TaskController<String>	processErrAsString(Process p, Executor exec) Create a task providing access to the given process's error output as a string.
static boolean	processIsTerminated(Process p) Test whether the given process has terminated.
static TaskController<String>	processOutAsString(Process p) Create a task providing access to the given process's standard output as a string.
static TaskController<String>	processOutAsString(Process p, Executor exec) Create a task providing access to the given process's standard output as a string.
static TaskController<Void>	runInThread(Runnable task) Execute the given task in a separate thread, and provide access to its result.
static TaskController<Void>	runInThread(Runnable task, boolean start) Execute the given task in a separate thread, and provide access to its result.
static void	sleep(long delay) Sleep for the given amount of time (milliseconds), or until an interrupt occurs.
static void	waitUntilMillis(Object obj, long futureTime) If the given time (based on System.currentTimeMillis()) has passed, throw a TimeoutException.
static void	waitUntilNanos(Object obj, long futureTime) If the given time (based on System.nanoTime()) has passed, throw a TimeoutException.
static void	work(long delay) Perform useless computation for the given amount of time (milliseconds), or until an interrupt occurs.

Methods inherited from class java.lang.Object

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

Field Detail

SLEEPING_RUNNABLE

public static final Runnable1<Long> SLEEPING_RUNNABLE

A runnable that simply sleeps for the specified amount of time (milliseconds), or until an interrupt occurs.

WORKING_RUNNABLE

public static final Runnable1<Long> WORKING_RUNNABLE

A runnable that performs useless computation for the specified amount of time (milliseconds).

THREAD_EXECUTOR

public static final Executor THREAD_EXECUTOR

A simple Executor that creates a new thread for each task; threads are identified by the name THREAD_EXECUTOR-n for some n.

DIRECT_EXECUTOR

public static final Executor DIRECT_EXECUTOR

A trivial Executor that simply runs each task directly. execute() blocks until the task completes.

Method Detail

sleep

public static void sleep(long delay)

Sleep for the given amount of time (milliseconds), or until an interrupt occurs.

work

public static void work(long delay)

Perform useless computation for the given amount of time (milliseconds), or until an interrupt occurs.

futureTimeNanos

public static long futureTimeNanos(long time,
                                   TimeUnit unit)

Get the expected value of System.nanoTime() after the given period has passed. Negative values for time return a time from the past. Note that, since an overflow wrap-around may occur at any time in the system's nanosecond clock, comparisons between the current time and this method's result are non-trivial. For example, to test whether the result time future has passed: System.nanoTime() - future > 0. (This checks that the current time is within a Long.MAX_VALUE range after future, regardless of the absolute numeric values. We can infer that (most likely) future is less than 292 years in the past, or (unlikely) future is more than 292 years in the future.)

futureTimeMillis

public static long futureTimeMillis(long time,
                                    TimeUnit unit)

Get the expected value of System.currentTimeMillis() after the given period of time has passed. Negative values for time return a time from the past. While the notes about overflow in futureTimeNanos(long, java.util.concurrent.TimeUnit) apply in principal here, an overflow of the 64-bit millisecond clock happens once every 600 million years, with the year 1970 at 0. So it's safe to use simple operators to make comparisons between the current time and this method's result.

waitUntilMillis

public static void waitUntilMillis(Object obj,
                                   long futureTime)
                            throws InterruptedException,
                                   TimeoutException

If the given time (based on System.currentTimeMillis()) has passed, throw a TimeoutException. Otherwise, invoke Object.wait(long) on the given object, which may return due to a notify() call, the timeout being reached, or a spurious wake-up. To distinguish between these possibilities, clients should wrap this call in a while loop: long t = futureTimeMillis(...); while (!condition) waitUntilMillis(lock, t); This loop either completes if the condition is satisfied or throws an appropriate exception due to an interrupt or timeout.

Parameters:

obj - Object whose wait() method will be invoked. Must be locked by the current thread.

futureTime - A millisecond time value based on System.currentTimeMillis() after which this method should no longer invoke obj.wait().

Throws:

InterruptedException - If the wait is interrupted.

TimeoutException - If, at invocation time, futureTime is in the past.

See Also:

futureTimeMillis(long, java.util.concurrent.TimeUnit)

waitUntilNanos

public static void waitUntilNanos(Object obj,
                                  long futureTime)
                           throws InterruptedException,
                                  TimeoutException

If the given time (based on System.nanoTime()) has passed, throw a TimeoutException. Otherwise, invoke Object.wait(long, int) on the given object, which may return due to a notify() call, the timeout being reached, or a spurious wake-up. To distinguish between these possibilities, clients should wrap this call in a while loop: long t = futureTimeNanos(...); while (!condition) waitUntilNanos(lock, t); This loop either completes if the condition is satisfied or throws an appropriate exception due to an interrupt or timeout.

Parameters:

obj - Object whose wait() method will be invoked. Must be locked by the current thread.

futureTime - A nanosecond time value based on System.nanoTime() after which this method should no longer invoke obj.wait().

Throws:

InterruptedException - If the wait is interrupted.

TimeoutException - If, at invocation time, futureTime is in the past.

See Also:

futureTimeNanos(long, java.util.concurrent.TimeUnit)

asCallable

public static <T> Callable<T> asCallable(Thunk<? extends T> thunk)

Wrap a thunk in a Callable interface. The call() method will not throw checked exceptions.

asTaskController

public static <T> TaskController<T> asTaskController(Future<? extends T> future)

Wrap a Future in a TaskController interface (which is also a Thunk). The state of the controller corresponds to the state of the Future; since Futures have no notion of "starting," the result is automatically "running" — it is never in a "paused" state.

asTaskController

public static <T> TaskController<T> asTaskController(Thunk<? extends Future<? extends T>> futureThunk)

Wrap a Future produced by a Thunk in a TaskController interface (which is also a Thunk). "Starting" the resulting controller corresponds to invoking futureThunk; subsequently, the state of the controller corresponds to the state of the Future.

runInThread

public static TaskController<Void> runInThread(Runnable task)

Execute the given task in a separate thread, and provide access to its result. This is a convenience method that sets start to true.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

See Also:

ExecutorTaskController

runInThread

public static TaskController<Void> runInThread(Runnable task,
                                               boolean start)

Execute the given task in a separate thread, and provide access to its result.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ExecutorTaskController

computeInThread

public static <R> TaskController<R> computeInThread(Thunk<? extends R> task)

Execute the given task in a separate thread, and provide access to its result. This is a convenience method that sets start to true.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

See Also:

ExecutorTaskController

computeInThread

public static <R> TaskController<R> computeInThread(Thunk<? extends R> task,
                                                    boolean start)

Execute the given task in a separate thread, and provide access to its result.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ExecutorTaskController

computeInThread

public static <I,R> IncrementalTaskController<I,R> computeInThread(IncrementalTask<? extends I,? extends R> task)

Execute the given task in a separate thread, and provide access to its results. This is a convenience method that sets start to true and ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

See Also:

ExecutorIncrementalTaskController

computeInThread

public static <I,R> IncrementalTaskController<I,R> computeInThread(IncrementalTask<? extends I,? extends R> task,
                                                                   boolean start)

Execute the given task in a separate thread, and provide access to its results. This is a convenience method that sets ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ExecutorIncrementalTaskController

computeInThread

public static <I,R> IncrementalTaskController<I,R> computeInThread(IncrementalTask<? extends I,? extends R> task,
                                                                   boolean start,
                                                                   boolean ignoreIntermediate)

Execute the given task in a separate thread, and provide access to its results.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

ignoreIntermediate - If true, all intermediate results will be immediately discarded.

See Also:

ExecutorIncrementalTaskController

computeWithExecutor

public static <R> TaskController<R> computeWithExecutor(Thunk<? extends R> task,
                                                        Executor exec)

Execute the given task with exec and provide access to its result. This is a convenience method that sets start to true.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

exec - An executor which is given the task to run when the controller is started.

See Also:

ExecutorTaskController

computeWithExecutor

public static <R> TaskController<R> computeWithExecutor(Thunk<? extends R> task,
                                                        Executor exec,
                                                        boolean start)

Execute the given task with exec and provide access to its result.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

exec - An executor which is given the task to run when the controller is started.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ExecutorTaskController

computeWithExecutor

public static <I,R> IncrementalTaskController<I,R> computeWithExecutor(IncrementalTask<? extends I,? extends R> task,
                                                                       Executor exec)

Execute the given task with exec and provide access to its result. This is a convenience method that sets start to true and ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

exec - An executor which is given the task to run when the controller is started.

See Also:

ExecutorIncrementalTaskController

computeWithExecutor

public static <I,R> IncrementalTaskController<I,R> computeWithExecutor(IncrementalTask<? extends I,? extends R> task,
                                                                       Executor exec,
                                                                       boolean start)

Execute the given task with exec and provide access to its result. This is a convenience method that sets ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

exec - An executor which is given the task to run when the controller is started.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ExecutorIncrementalTaskController

computeWithExecutor

public static <I,R> IncrementalTaskController<I,R> computeWithExecutor(IncrementalTask<? extends I,? extends R> task,
                                                                       Executor exec,
                                                                       boolean start,
                                                                       boolean ignoreIntermediate)

Execute the given task with exec and provide access to its result.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

exec - An executor which is given the task to run when the controller is started.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

ignoreIntermediate - If true, all intermediate results will be immediately discarded.

See Also:

ExecutorIncrementalTaskController

computeInProcess

public static <R> TaskController<R> computeInProcess(Thunk<? extends R> task)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

This is a convenience method that uses JVMBuilder.DEFAULT and sets start to true.

Parameters:

task - A task to perform. Will be abruptly terminated with the process if canceled while running.

See Also:

ProcessTaskController

computeInProcess

public static <R> TaskController<R> computeInProcess(Thunk<? extends R> task,
                                                     boolean start)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

This is a convenience method that uses JVMBuilder.DEFAULT.

Parameters:

task - A task to perform. Will be abruptly terminated with the process if canceled while running.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ProcessTaskController

computeInProcess

public static <R> TaskController<R> computeInProcess(Thunk<? extends R> task,
                                                     JVMBuilder jvmBuilder)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

Parameters:

task - A task to perform. Will be abruptly terminated with the process if canceled while running.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the task's class, ConcurrentUtil, and their dependencies. If the current JVM has property values for plt.*, those values will be added to jvmBuilder (unless they're already set to something else).

See Also:

ProcessTaskController

computeInProcess

public static <R> TaskController<R> computeInProcess(Thunk<? extends R> task,
                                                     JVMBuilder jvmBuilder,
                                                     boolean start)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

Parameters:

task - A task to perform. Will be abruptly terminated with the process if canceled while running.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the task's class, ConcurrentUtil, and their dependencies. If the current JVM has property values for plt.*, those values will be added to jvmBuilder (unless they're already set to something else).

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ProcessTaskController

computeInProcess

public static <I,R> IncrementalTaskController<I,R> computeInProcess(IncrementalTask<? extends I,? extends R> task)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

This is a convenience method that uses JVMBuilder.DEFAULT and sets start to true and ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

See Also:

ProcessIncrementalTaskController

computeInProcess

public static <I,R> IncrementalTaskController<I,R> computeInProcess(IncrementalTask<? extends I,? extends R> task,
                                                                    boolean start)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

This is a convenience method that uses JVMBuilder.DEFAULT and sets ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ProcessIncrementalTaskController

computeInProcess

public static <I,R> IncrementalTaskController<I,R> computeInProcess(IncrementalTask<? extends I,? extends R> task,
                                                                    JVMBuilder jvmBuilder)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

This is a convenience method that sets start to true and ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the task's class, ConcurrentUtil, and their dependencies. If the current JVM has property values for plt.*, those values will be added to jvmBuilder (unless they're already set to something else).

See Also:

ProcessIncrementalTaskController

computeInProcess

public static <I,R> IncrementalTaskController<I,R> computeInProcess(IncrementalTask<? extends I,? extends R> task,
                                                                    JVMBuilder jvmBuilder,
                                                                    boolean start)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

This is a convenience method that sets ignoreIntermediate to false.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the task's class, ConcurrentUtil, and their dependencies. If the current JVM has property values for plt.*, those values will be added to jvmBuilder (unless they're already set to something else).

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

See Also:

ProcessIncrementalTaskController

computeInProcess

public static <I,R> IncrementalTaskController<I,R> computeInProcess(IncrementalTask<? extends I,? extends R> task,
                                                                    JVMBuilder jvmBuilder,
                                                                    boolean start,
                                                                    boolean ignoreIntermediate)

Execute the given task in a separate process and provide access to its result. The task and the return value must be serializable. Typically, the subprocess terminates when the TaskController enters a finished state. However, if task spawns additional threads and no exceptions are thrown by the controller's value() method, the subprocess may remain alive indefinitely; the remaining threads are responsible for process termination.

Parameters:

task - A task to perform. Should respond to an interrupt by throwing an InterruptedException wrapped in a WrappedException.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the task's class, ConcurrentUtil, and their dependencies. If the current JVM has property values for plt.*, those values will be added to jvmBuilder (unless they're already set to something else).

start - If true, the task will be started before returning; otherwise, the client should invoke TaskController.start() on the returned controller.

ignoreIntermediate - If true, all intermediate results will be immediately discarded.

See Also:

ProcessIncrementalTaskController

exportInProcess

public static Remote exportInProcess(Thunk<? extends Remote> factory)
                              throws InterruptedException,
                                     ExecutionException,
                                     IOException

Export the given RMI object in a new process and return the exported stub. If any exception occurs, the process is destroyed. This convenience method uses JVMBuilder.DEFAULT to start the new process.

Parameters:

factory - A thunk to evaluate in the remote JVM, producing an object that can be exported via UnicastRemoteObject.exportObject(Remote, int). The factory must be serializable.

Returns:

An RMI proxy that can be cast to the remote interface type of the object returned by factory. (See Remote for the definition of "remote interface.")

Throws:

IOException - If a problem occurs in starting the new process or serializing factory.

ExecutionException - If an exception occurs in factory or while exporting the result.

InterruptedException - If this thread is interrupted while waiting for the result to be produced.

exportInProcess

public static Remote exportInProcess(Thunk<? extends Remote> factory,
                                     JVMBuilder jvmBuilder)
                              throws InterruptedException,
                                     ExecutionException,
                                     IOException

Export the given RMI object in a new process and return the exported stub. If any exception occurs, the process is destroyed.

Parameters:

factory - A thunk to evaluate in the remote JVM, producing an object that can be exported via UnicastRemoteObject.exportObject(Remote, int). The factory must be serializable.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the factory's class, ConcurrentUtil, and their dependencies.

Returns:

An RMI proxy that can be cast to the remote interface type of the object returned by factory. (See Remote for the definition of "remote interface.")

Throws:

IOException - If a problem occurs in starting the new process or serializing factory.

ExecutionException - If an exception occurs in factory or while exporting the result.

InterruptedException - If this thread is interrupted while waiting for the result to be produced.

exportInProcess

public static Remote exportInProcess(Thunk<? extends Remote> factory,
                                     JVMBuilder jvmBuilder,
                                     Runnable1<? super Process> onExit)
                              throws InterruptedException,
                                     ExecutionException,
                                     IOException

Export the given RMI object in a new process and return the exported stub. If any exception occurs, the process is destroyed.

Parameters:

factory - A thunk to evaluate in the remote JVM, producing an object that can be exported via UnicastRemoteObject.exportObject(Remote, int). The factory must be serializable.

jvmBuilder - A JVMBuilder set up with the necessary subprocess parameters. The class path must include the factory's class, ConcurrentUtil, and their dependencies. If the current JVM has property values for plt.*, those values will be added to jvmBuilder (unless they're already set to something else).

onExit - Code to execute when the process exits, assuming a result is successfully returned. May be null, indicating that nothing should be run. If an exception occurs here, the process is destroyed immediately and this listener will not be invoked.

Returns:

An RMI proxy that can be cast to the remote interface type of the object returned by factory. (See Remote for the definition of "remote interface.")

Throws:

IOException - If a problem occurs in starting the new process or serializing factory.

ExecutionException - If an exception occurs in factory or while exporting the result.

InterruptedException - If this thread is interrupted while waiting for the result to be produced.

processIsTerminated

public static boolean processIsTerminated(Process p)

Test whether the given process has terminated.

onProcessExit

public static void onProcessExit(Process p,
                                 Runnable1<? super Process> listener)

Create a daemon thread that will invoke Process.waitFor() on the given process, then run the given listener. If the thread is interrupted while blocked on waitFor(), the listener will not be run.

discardProcessOutput

public static void discardProcessOutput(Process p)

Create two threads to continually discard the contents of the given process's output and error streams. If, instead, the streams are simply ignored, the system buffers may fill up, causing the process to block (see the class documentation for Process; experimentation under Java 5 shows the buffer size to be approximately 4 KB).

copyProcessOutput

public static void copyProcessOutput(Process p,
                                     OutputStream out,
                                     OutputStream err)

Create two threads to continually copy the contents of the given process's output and error streams to the given destinations. This is a convenience method that invokes copyProcessOut(Process, OutputStream) and copyProcessErr(Process, OutputStream).

discardProcessOut

public static Thread discardProcessOut(Process p)

Create a thread that will continually discard the contents of the given process's standard output. If, instead, the stream is simply ignored, the system buffer may fill up, causing the process to block (see the class documentation for Process; experimentation under Java 5 shows the buffer size to be approximately 4 KB).

Returns:

The thread performing the discard operation, already started.

copyProcessOut

public static Thread copyProcessOut(Process p,
                                    OutputStream out)

Create a thread that will continually copy the contents of the given process's standard output to another output stream. This is a convenience method that sets close to true.

Returns:

The thread performing the copy operation, already started.

copyProcessOut

public static Thread copyProcessOut(Process p,
                                    OutputStream out,
                                    boolean close)

Create a thread that will continually copy the contents of the given process's standard output to another output stream. Processing continues until the end-of-file is reached. If close is true, out will then be closed.

Returns:

The thread performing the copy operation, already started.

processOutAsString

public static TaskController<String> processOutAsString(Process p)

Create a task providing access to the given process's standard output as a string. The result is not available until an end-of-file is reached, but it is buffered locally to prevent blocking. A separate non-daemon thread performs this buffering.

processOutAsString

public static TaskController<String> processOutAsString(Process p,
                                                        Executor exec)

Create a task providing access to the given process's standard output as a string. The result is not available until an end-of-file is reached, but it is buffered locally to prevent blocking. A task passed to exec performs this buffering.

discardProcessErr

public static Thread discardProcessErr(Process p)

Create a thread that will continually discard the contents of the given process's standard output. If, instead, the stream is simply ignored, the system buffer may fill up, causing the process to block (see the class documentation for Process; experimentation under Java 5 shows the buffer size to be approximately 4 KB).

Returns:

The thread performing the discard operation, already started.

copyProcessErr

public static Thread copyProcessErr(Process p,
                                    OutputStream err)

Create a thread that will continually copy the contents of the given process's error output to another output stream. This is a convenience method that sets close to false.

Returns:

The thread performing the copy operation, already started.

copyProcessErr

public static Thread copyProcessErr(Process p,
                                    OutputStream err,
                                    boolean close)

Create a thread that will continually copy the contents of the given process's error output to another output stream. Processing continues until the end-of-file is reached. If close is true, out will then be closed.

Returns:

The thread performing the copy operation, already started.

processErrAsString

public static TaskController<String> processErrAsString(Process p)

Create a task providing access to the given process's error output as a string. The result is not available until an end-of-file is reached, but it is buffered locally to prevent blocking. A separate non-daemon thread performs this buffering.

processErrAsString

public static TaskController<String> processErrAsString(Process p,
                                                        Executor exec)

Create a task providing access to the given process's error output as a string. The result is not available until an end-of-file is reached, but it is buffered locally to prevent blocking. A task passed to exec performs this buffering.

getProperties

public static Properties getProperties(String... prefixes)

Get a subset of the system properties for names that match at least one of the given prefixes.

Throws:

SecurityException - As in System.getProperties().

getPropertiesAsMap

public static Map<String,String> getPropertiesAsMap(String... prefixes)

Get a subset of the system properties for names that match at least one of the given prefixes. Returns a String map; in the unusual case that a value is not a String, it is converted via toString().

Throws:

SecurityException - As in System.getProperties().