Class 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 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
      • 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, 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​(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, 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