dev.nm.misc.parallel

Class ParallelExecutor

java.lang.Object

dev.nm.misc.parallel.ParallelExecutor

public class ParallelExecutor
extends Object

This class provides a framework for executing an algorithm in parallel. A thread pool is created when executing a list of tasks.

Caution: Avoid using another executor within parallelized calls, this would create numerous threads, leading to much memory consumption and huge overhead for thread switching. It is recommended to parallelize the outermost-scoped tasks.

Constructor Summary

Constructors

Constructor and Description
ParallelExecutor() Creates an instance using default concurrency number, which is the number of available processors returned by Runtime.getRuntime().availableProcessors()
ParallelExecutor(int concurrency) Creates an instance with a specified concurrency number.
ParallelExecutor(String executorName) Creates an instance with a specified executor name.
ParallelExecutor(String executorName, int concurrency) Creates an instance with a specified concurrency number, and a name of the executor.

Method Summary

Modifier and Type	Method and Description
<T> void	conditionalForEach(boolean conditionToParallelize, Iterable<T> iterable, IterationBody<T> body) Calls forEach only if conditionToParallelize is true.
void	conditionalForLoop(boolean conditionToParallelize, int start, int end, int increment, LoopBody body) Runs a parallel for-loop only if conditionToParallelize is true.
void	conditionalForLoop(boolean conditionToParallelize, int start, int end, LoopBody body) Calls conditionalForLoop with increment of 1.
<T> List<T>	executeAll(Callable<T>... tasks) Executes an arbitrary number of Callable tasks, and returns a list of results in the same order.
<T> List<T>	executeAll(List<? extends Callable<T>> tasks) Executes a list of Callable tasks, and returns a list of results in the same sequential order as tasks.
<T> T	executeAny(Callable<T>... tasks) Executes a list of tasks in parallel, and returns the result from the earliest successfully completed tasks (without throwing an exception).
<T> T	executeAny(List<? extends Callable<T>> tasks) Executes a list of tasks in parallel, and returns the result from the earliest successfully completed tasks (without throwing an exception).
<T> void	forEach(Iterable<T> iterable, IterationBody<T> body) Runs a "foreach" loop in parallel.
void	forLoop(int start, int end, int increment, LoopBody body) Runs a for-loop in parallel.
void	forLoop(int start, int end, LoopBody body) Calls forLoop with increment of 1.
int	getConcurrency() Returns the number of threads used for parallel execution.
static ParallelExecutor	getSharedInstance() Gets the globally shared executor.
boolean	isWorkerThread() Tests membership in this executor without depending on thread names.
void	shutdown() Shuts down the executor gracefully.

Methods inherited from class java.lang.Object

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

Constructor Detail

ParallelExecutor

public ParallelExecutor()

Creates an instance using default concurrency number, which is the number of available processors returned by

 Runtime.getRuntime().availableProcessors()
 

ParallelExecutor

public ParallelExecutor(String executorName)

Creates an instance with a specified executor name.

Parameters:

executorName - the executor name (for debug purpose)

ParallelExecutor

public ParallelExecutor(int concurrency)

Creates an instance with a specified concurrency number.

Parameters:

concurrency - the maximum number of threads can be used when executing a list of tasks

ParallelExecutor

public ParallelExecutor(String executorName,
                        int concurrency)

Creates an instance with a specified concurrency number, and a name of the executor.

Parameters:

executorName - the executor name (for debug purpose)

concurrency - the maximum number of threads can be used when executing a list of tasks

Method Detail

getSharedInstance

public static ParallelExecutor getSharedInstance()

Gets the globally shared executor.

WARNING: Please make sure that the tasks submitted to this executor do NOT call this executor again to avoid deadlock. Create your own executor if you are not 100% sure about this.

Returns:

the shared instance

shutdown

public void shutdown()

Shuts down the executor gracefully. Calling this method will terminate the thread pool used by this executor, and hence return resources to the JVM.

getConcurrency

public int getConcurrency()

Returns the number of threads used for parallel execution.

Returns:

the concurrency of this executor

isWorkerThread

public boolean isWorkerThread()

Tests membership in this executor without depending on thread names.

Returns:

true when called by one of this executor's workers

executeAll

public <T> List<T> executeAll(List<? extends Callable<T>> tasks)
                       throws MultipleExecutionException

Executes a list of Callable tasks, and returns a list of results in the same sequential order as tasks.

Type Parameters:

T - the type of results

Parameters:

tasks - the list of tasks

Returns:

a list of results

Throws:

MultipleExecutionException - if one or more tasks throws an exception

executeAll

public <T> List<T> executeAll(Callable<T>... tasks)
                       throws MultipleExecutionException

Executes an arbitrary number of Callable tasks, and returns a list of results in the same order. This is a convenient method and is the same as calling:

 executeAll(Arrays.<Callable<T>>asList(tasks));
 

Type Parameters:

T - the type of results

Parameters:

tasks - the list of tasks

Returns:

a list of results

Throws:

MultipleExecutionException - if one or more tasks throws an exception

executeAny

public <T> T executeAny(List<? extends Callable<T>> tasks)
                 throws ExecutionException

Executes a list of tasks in parallel, and returns the result from the earliest successfully completed tasks (without throwing an exception).

Type Parameters:

T - the type of results

Parameters:

tasks - the list of tasks

Returns:

the earliest returned results

Throws:

ExecutionException - if no task successfully completes

executeAny

public <T> T executeAny(Callable<T>... tasks)
                 throws ExecutionException

Executes a list of tasks in parallel, and returns the result from the earliest successfully completed tasks (without throwing an exception). This is a convenient method and is the same as calling:

 executeAny(Arrays.<Callable<T>>asList(tasks));
 

Type Parameters:

T - the type of results

Parameters:

tasks - the list of tasks

Returns:

the earliest returned results

Throws:

ExecutionException - if no task successfully completes

forLoop

public void forLoop(int start,
                    int end,
                    LoopBody body)
             throws MultipleExecutionException

Calls forLoop with increment of 1.

Parameters:

start - the first loop index (inclusive)

end - the last loop index (exclusive)

body - the loop body

Throws:

MultipleExecutionException - if one or more partitioned for-loop throws an exception

forLoop

public void forLoop(int start,
                    int end,
                    int increment,
                    LoopBody body)
             throws MultipleExecutionException

Runs a for-loop in parallel. A huge for-loop is partitioned into roughly equal size, and each partition is then run by a thread. This is similar to running a normal for-loop construct:

 for (int i = start; i < end; i += increment) {
     body.run(i);
 }
 

Parameters:

start - the first loop index (inclusive)

end - the last loop index (exclusive)

increment - the increment of the loop index in each iteration

body - the loop body

Throws:

MultipleExecutionException - if one or more partitioned for-loop throws an exception

conditionalForLoop

public void conditionalForLoop(boolean conditionToParallelize,
                               int start,
                               int end,
                               int increment,
                               LoopBody body)
                        throws MultipleExecutionException

Runs a parallel for-loop only if conditionToParallelize is true. Otherwise, or when called from this executor's own worker, the loop body runs on the calling thread to avoid thread-starvation deadlock.

Parameters:

conditionToParallelize - the condition to parallelize the for-loop execution

start - the first loop index (inclusive)

end - the last loop index (exclusive)

increment - the increment of the loop index in each iteration

body - the loop body

Throws:

MultipleExecutionException - if one or more partitioned for-loop throws an exception

conditionalForLoop

public void conditionalForLoop(boolean conditionToParallelize,
                               int start,
                               int end,
                               LoopBody body)
                        throws MultipleExecutionException

Calls conditionalForLoop with increment of 1.

Parameters:

conditionToParallelize - the condition to parallelize the for-loop execution

start - the first loop index (inclusive)

end - the last loop index (exclusive)

body - the loop body

Throws:

MultipleExecutionException - if one or more partitioned for-loop throws an exception

forEach

public <T> void forEach(Iterable<T> iterable,
                        IterationBody<T> body)
                 throws MultipleExecutionException

Runs a "foreach" loop in parallel. Multiple threads take elements from the iterable collection and run the loop body in parallel. Threads are coordinated such that two different threads will not run the loop body for the same element in the collection. This is similar to running a normal "foreach" construct:

 for (T item : collection) {
     body.run(item);
 }
 

Type Parameters:

T - data type of elements in iterable

Parameters:

iterable - the Iterable collection

body - the loop body

Throws:

MultipleExecutionException - if one or more threads throws an exception

conditionalForEach

public <T> void conditionalForEach(boolean conditionToParallelize,
                                   Iterable<T> iterable,
                                   IterationBody<T> body)
                            throws MultipleExecutionException

Calls forEach only if conditionToParallelize is true. Otherwise, or when called from this executor's own worker, the loop body runs on the calling thread to avoid thread-starvation deadlock.

Type Parameters:

T - data type of elements in iterable

Parameters:

conditionToParallelize - the condition to parallelize the "foreach" execution

iterable - the Iterable collection

body - the loop body

Throws:

MultipleExecutionException - if one or more threads throws an exception