Package 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 Description ParallelExecutor()
Creates an instance using default concurrency number, which is the number of available processors returned byParallelExecutor(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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description <T> void
conditionalForEach(boolean conditionToParallelize, Iterable<T> iterable, IterationBody<T> body)
void
conditionalForLoop(boolean conditionToParallelize, int start, int end, int increment, LoopBody body)
Runs a parallel for-loop only ifconditionToParallelize
istrue
.void
conditionalForLoop(boolean conditionToParallelize, int start, int end, LoopBody body)
CallsconditionalForLoop
withincrement
of 1.<T> List<T>
executeAll(Callable<T>... tasks)
Executes an arbitrary number ofCallable
tasks, and returns a list of results in the same order.<T> List<T>
executeAll(List<? extends Callable<T>> tasks)
Executes a list ofCallable
tasks, and returns a list of results in the same sequential order astasks
.<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)
CallsforLoop
withincrement
of 1.int
getConcurrency()
Returns the number of threads used for parallel execution.static ParallelExecutor
getSharedInstance()
Gets the globally shared executor.void
shutdown()
Shuts down the executor gracefully.
-
-
-
Constructor Detail
-
ParallelExecutor
public ParallelExecutor()
Creates an instance using default concurrency number, which is the number of available processors returned byRuntime.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
-
executeAll
public <T> List<T> executeAll(List<? extends Callable<T>> tasks) throws MultipleExecutionException
Executes a list ofCallable
tasks, and returns a list of results in the same sequential order astasks
.- 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 ofCallable
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
CallsforLoop
withincrement
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 iterationbody
- 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 ifconditionToParallelize
istrue
. Otherwise, the loop body will be executed in a single thread.- Parameters:
conditionToParallelize
- the condition to parallelize the for-loop executionstart
- the first loop index (inclusive)end
- the last loop index (exclusive)increment
- the increment of the loop index in each iterationbody
- 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
CallsconditionalForLoop
withincrement
of 1.- Parameters:
conditionToParallelize
- the condition to parallelize the for-loop executionstart
- 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 initerable
- Parameters:
iterable
- theIterable
collectionbody
- 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
CallsforEach
only ifconditionToParallelize
istrue
. Otherwise, the loop body will be executed in a single thread.- Type Parameters:
T
- data type of elements initerable
- Parameters:
conditionToParallelize
- the condition to parallelize the "foreach" executioniterable
- theIterable
collectionbody
- the loop body- Throws:
MultipleExecutionException
- if one or more threads throws an exception
-
-