com.numericalmethod.suanshu.parallel

Class ParallelExecutor

java.lang.Object

com.numericalmethod.suanshu.parallel.ParallelExecutor

public class ParallelExecutor
extends java.lang.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.

Method Summary

Modifier and Type	Method and Description
<T> void	conditionalForEach(boolean conditionToParallelize, java.lang.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> java.util.List<T>	executeAll(java.util.concurrent.Callable<T>... tasks) Executes an arbitrary number of Callable tasks, and returns a list of results in the same order.
<T> java.util.List<T>	executeAll(java.util.List<? extends java.util.concurrent.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(java.util.concurrent.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(java.util.List<? extends java.util.concurrent.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(java.lang.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() Gets the number of concurrent threads.
static ParallelExecutor	getInstance()
static void	setConcurrencyLevel(int concurrency) Sets the concurrency level for the ParallelExecutor.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static ParallelExecutor getInstance()

setConcurrencyLevel

public static void setConcurrencyLevel(int concurrency)

Sets the concurrency level for the ParallelExecutor.

Parameters:

concurrency - concurrency level to set. -1 indicates that there should be one thread per processor.

getConcurrency

public int getConcurrency()

Gets the number of concurrent threads.

Returns:

number of concurrent threads.

executeAll

public <T> java.util.List<T> executeAll(java.util.List<? extends java.util.concurrent.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> java.util.List<T> executeAll(java.util.concurrent.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(java.util.List<? extends java.util.concurrent.Callable<T>> tasks)
                 throws java.util.concurrent.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:

java.util.concurrent.ExecutionException - if no task successfully completes

executeAny

public <T> T executeAny(java.util.concurrent.Callable<T>... tasks)
                 throws java.util.concurrent.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:

java.util.concurrent.ExecutionException - if no task successfully completes

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

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

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, the loop body will be executed in a single thread.

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(java.lang.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,
                                   java.lang.Iterable<T> iterable,
                                   IterationBody<T> body)
                            throws MultipleExecutionException

Calls forEach only if conditionToParallelize is true. Otherwise, the loop body will be executed in a single thread.

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