edu.rice.cs.plt.concurrent
Class IncrementalTaskController<I,R>

java.lang.Object
  edu.rice.cs.plt.concurrent.TaskController<R>
      edu.rice.cs.plt.concurrent.IncrementalTaskController<I,R>

All Implemented Interfaces:

ResolvingThunk<R>, Thunk<R>, Future<R>

Direct Known Subclasses:

ExecutorIncrementalTaskController, ProcessIncrementalTaskController, SwingWorker

public abstract class IncrementalTaskController<I,R>
extends TaskController<R>

Provides access to a concurrent task that produces incremental results. Adds a pause() method, more responsive cancellation, and access to intermediate computation results via steps() and intermediateQueue().

To implement a concrete instance, a subclass must provide TaskController.doStart(), doPause(), TaskController.doStop(), and, optionally, TaskController.discard().

Nested Class Summary

protected class	IncrementalTaskController.CanceledPausingState A PausingState that has been canceled while waiting for the pause to complete.
protected class	IncrementalTaskController.FreshPausingState Simple instance of PausingState.
protected class	IncrementalTaskController.PausedStartingState A StartingState that has been paused while waiting for startup to complete.
protected class	IncrementalTaskController.PausedState The tasked has been started and then paused.
protected class	IncrementalTaskController.PausingState pause() has been invoked on a RunningState, but the task has not yet paused.
protected class	IncrementalTaskController.StartedPausingState A PausingState that has been started while waiting for the pause to complete.

Nested classes/interfaces inherited from class edu.rice.cs.plt.concurrent.TaskController

TaskController.CanceledStartingState, TaskController.CanceledState, TaskController.CancelingState, TaskController.CleanlyFinishedState, TaskController.ComputingState, TaskController.ExecutionExceptionState, TaskController.FinishedState, TaskController.FreshStartingState, TaskController.FreshState, TaskController.InternalExceptionState, TaskController.RunningState, TaskController.StartingState, TaskController.State, TaskController.Status, TaskController.WaitingState

Field Summary

Fields inherited from class edu.rice.cs.plt.concurrent.TaskController

state

Constructor Summary

protected	IncrementalTaskController() Sets ignoreIntermediate to false.
protected	IncrementalTaskController(boolean ignoreIntermediate) If ignoreIntermediate, intermediate results will not be enqueued.

Method Summary

protected abstract void	doPause() Pause computation and call paused().
protected abstract void	doResume() Resume computation (after a pause) and call TaskController.started().
ListenerSet.Sink	intermediateListeners() Access the ListenerSet responding to the availability of intermediate results.
BlockingQueue<I>	intermediateQueue() Get the queue for storing intermediate results.
void	pause() Request that the task be paused.
protected void	paused()
protected void	stepped(I intermediateResult) Record an intermediate result.
int	steps() Get the number of intermediate steps the task has taken.

Methods inherited from class edu.rice.cs.plt.concurrent.TaskController

attemptGet, attemptGet, cancel, cancel, discard, doStart, doStop, finishedCleanly, finishedWithImplementationException, finishedWithTaskException, finishListeners, get, get, get, hasValue, isCanceled, isCancelled, isDone, isResolved, runningState, start, started, status, stopped, value

Methods inherited from class java.lang.Object

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

Constructor Detail

IncrementalTaskController

protected IncrementalTaskController()

Sets ignoreIntermediate to false.

IncrementalTaskController

protected IncrementalTaskController(boolean ignoreIntermediate)

If ignoreIntermediate, intermediate results will not be enqueued. (They will, however, be passed to any listeners and counted by steps().)

Method Detail

steps

public int steps()

Get the number of intermediate steps the task has taken. If storeIntermediate, at least this many values have been added to the intermediateQueue.

intermediateQueue

public BlockingQueue<I> intermediateQueue()

Get the queue for storing intermediate results. Throws an exception if storeIntermediate is false; otherwise each intermediate result is added to this queue. Clients can check the controller's status to determine if no additional results will be enqueued. However, there is no guarantee (in general) that a running task will produce an intermediate result before completing. (The task being run may follow some convention for indicating termination via the queue.) While the result is intended to be used only for read operations, given the lack of a nice interface for separating queue reads from queue writes, the result allows write access to the queue as well.

IncrementalTaskController implementations should invoke stepped(I) to add items to the queue, rather than doing so directly.

Throws:

IllegalStateException - If storeIntermediate is false.

intermediateListeners

public ListenerSet.Sink intermediateListeners()

Access the ListenerSet responding to the availability of intermediate results. Registered listeners will be run for each intermediate result that becomes available.

pause

public void pause()

Request that the task be paused. After pausing, the task will not continue executing unless TaskController.start() is invoked. If the the task is PAUSED or FINISHED, has no effect.

Throws:

CancellationException - If the task is CANCELED.

doPause

protected abstract void doPause()

Pause computation and call paused(). If pausing does not occur immediately, the paused() call may occur in a different thread. Will only be called after started() has been invoked. When execution should resume again, doStart() will be invoked (but only after paused() has been called). In order to support responsive canceling, a call to doStop() may occur concurrently, or before paused() is called.

doResume

protected abstract void doResume()

Resume computation (after a pause) and call TaskController.started(). If starting does not occur immediately (for example, blocking occurs first), the started() call may occur in a different thread.

paused

protected void paused()

stepped

protected void stepped(I intermediateResult)

Record an intermediate result. Should only be called while the controller is in a running state.