org.amino.pattern.internal
Interface MasterWorker<S,T>

Type Parameters:

S - indicates the type of the input work item.

T - indicates the type of the output work item.

public interface MasterWorker<S,T>

This is a simple master/worker pattern. The master thread creates an instance of the pattern, provides work items to be processed, and is signaled upon completion. The master thread may wait for completion (synchronous) or may poll for completion (asynchronous). A master/worker pattern may be static or dynamic. In a static master/worker, execution proceeds in two distinct phases - first all of the work items are submitted and then the workers execute by consuming work items. Work items may not be submitted once execution has begun. In a dynamic master/worker, submission of work and the execution of workers proceeds concurrently. Furthermore, a worker task may opt to add new work items during its execution.

Author:

blainey

Nested Class Summary

static class

MasterWorker.ResultKey An abstract type used to hold keys for result values.

Method Summary

boolean	execute() Begin processing of the work items submitted.
boolean	execute(long timeout, java.util.concurrent.TimeUnit unit) Begin processing of the work items submitted.
void	finished() Indicate to the master/worker that there is not more work coming.
java.util.Collection<T>	getAllResults() Obtain all of the results from the processing work items.
boolean	isCompleted() Poll an executing master/worker for completion.
boolean	isStatic() Determine if a master/worker is static.
int	numWorkers() Get the number of active workers.
T	result(MasterWorker.ResultKey k) Obtain the results from the processing of a work item.
void	shutdown() Shutdown the master/worker.
MasterWorker.ResultKey	submit(S w) Submit a work item for processing.
MasterWorker.ResultKey	submit(S w, long timeout, java.util.concurrent.TimeUnit unit) Submit a work item for processing and block until it is either submitted successfully or the specified timeout period has expired.
boolean	waitForCompletion() Wait until all workers have completed.
boolean	waitForCompletion(long timeout, java.util.concurrent.TimeUnit unit) Wait until all workers have completed or the specified timeout period expires.

Method Detail

numWorkers

int numWorkers()

Get the number of active workers.

Returns:

The number of workers that are part of this pattern.

submit

MasterWorker.ResultKey submit(S w)

Submit a work item for processing. The call is non-blocking. If, for any reason, the work item cannot be immediately submitted for execution, then a false result will be returned.

Parameters:

w - Work item.

Returns:

Reference to a result key if work item was successfully submitted. null if the work item could not immediately be submitted for processing.

submit

MasterWorker.ResultKey submit(S w,
                              long timeout,
                              java.util.concurrent.TimeUnit unit)

Submit a work item for processing and block until it is either submitted successfully or the specified timeout period has expired.

Parameters:

w - Work item.

timeout - Time out value.

unit - Time out unit.

Returns:

Reference to a result key if work item was successfully submitted. null if the work item could not be submitted, if the time out period expired, or if the thread was interrupted while waiting.

finished

void finished()

Indicate to the master/worker that there is not more work coming. In a static master/worker, this is implied by beginning execution.

execute

boolean execute(long timeout,
                java.util.concurrent.TimeUnit unit)
                throws java.util.concurrent.TimeoutException,
                       java.util.concurrent.ExecutionException,
                       java.lang.InterruptedException

Begin processing of the work items submitted. If the master/worker is static, then further work items may be submitted for processing after execution has started. The calling thread blocks until all work items have been processed, the specified timeout value has been reached or if execution was terminated for some abnormal reason. In the event of successful execution, all worker threads will be in a completed state prior to control returning to the calling thread. In the event of timeout or abnormal termination, worker threads will be interrupted using the Thread.interrupt() method. Upon successful completion, results may be obtained using the result methods.

Parameters:

timeout - The timeout value.

unit - The time units.

Returns:

• true if execution completes normally
• false if the master/worker is not ready to execute (because it hasn't compleed a prior execution)

Throws:

java.util.concurrent.TimeoutException - If the specified timeout period expired before completion of all work items.

java.lang.InterruptedException - If execution of any of the threads was interrupted.

java.util.concurrent.ExecutionException - If any of the worker threads encounted some runtime exception.

execute

boolean execute()

Begin processing of the work items submitted. If the master/worker is static, then further work items may be submitted for processing after execution has started. Control returns to the calling thread once all tasks have begun execution. The calling thread may subsequently poll or wait for completion.

Returns:

• true if execution started normally
• false if the master/worker is not ready to execute (because it hasn't compleed a prior execution)

isStatic

boolean isStatic()

Determine if a master/worker is static.

Returns:

• true if the master/worker is static
• false if the master/worker is dynamic

isCompleted

boolean isCompleted()

Poll an executing master/worker for completion.

Returns:

• true if the master/worker is complete
• false if it is executing or not yet started

waitForCompletion

boolean waitForCompletion(long timeout,
                          java.util.concurrent.TimeUnit unit)

Wait until all workers have completed or the specified timeout period expires.

Parameters:

timeout - time out

unit - time unit

Returns:

• true if all tasks are complete
• false otherwise (timeout or some other abnormal condition)

waitForCompletion

boolean waitForCompletion()

Wait until all workers have completed.

Returns:

• true if all tasks are complete
• false otherwise (some abnormal condition has arisen)

result

T result(MasterWorker.ResultKey k)

Obtain the results from the processing of a work item.

Parameters:

k - A result key, obtained from a prior call to "submit"

Returns:

The results produced by a worker task, or null if the results are not available.

getAllResults

java.util.Collection<T> getAllResults()

Obtain all of the results from the processing work items.

Returns:

The results produced by all worker tasks, or null if one or more workers are still active.

shutdown

void shutdown()

Shutdown the master/worker. This releases resources that may be held by the master/worker.