Package org.jppf.client.concurrent

Class JPPFExecutorService

java.lang.Object
org.jppf.client.event.JobListenerAdapter
org.jppf.client.concurrent.JPPFExecutorService
All Implemented Interfaces:
Executor, ExecutorService, EventListener, JobListener
public class JPPFExecutorService extends JobListenerAdapter implements ExecutorService
Implementation of an ExecutorService wrapper around a JPPFClient.

This executor has two modes in which it functions:

1) Standard mode: in this mode each task or set of tasks submitted via one of the invokeXXX() or submit() methods is sent immediately to the server in its own JPPF job.

2) Batch mode: the JPPFExecutorService can be configured to only send tasks to the server when a number of tasks, submitted via one of the invokeXXX() or submit() methods, has been reached, or when a timeout specified in milliseconds has expired, or a combination of both.
This facility is designed to optimize the task execution throughput, especially when many individual tasks are submitted using one of the submit() methods. This way, the tasks are sent to the server as a single job, instead of one job per task, and the execution will fully benefit from the parallel features of the JPPF server, including scheduling, load-balancing and parallel I/O.

In batch mode, the following behavior is to be noted:

  • If both size-based and time-based batching are used, tasks will be sent whenever one of the two thresholds is reached. Whenever this happens, both counters are reset. For instance, if the size-based threshold is reached, then the time-based counter will be reset as well, and the timeout counting will start from 0 again
  • When a collection of tasks is submitted via one of the invokeXXX() methods, they are guaranteed to be all sent together in the same JPPF job. This is the one exception to the batch size threshold.
  • If one of the threshold is changed while tasks are still pending execution, the behavior is unspecified
Author:
Laurent Cohen
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    JPPFExecutorService(JPPFClient client)
    Initialize this executor service with the specified JPPF client.
    JPPFExecutorService(JPPFClient client, int batchSize, long batchTimeout)
    Initialize this executor service with the specified JPPF client, batch size and batch tiemout.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    awaitTermination(long timeout, TimeUnit unit)
    Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
    void
    execute(Runnable command)
    Executes the given command at some time in the future.
    int
    getBatchSize()
    Get the minimum number of tasks that must be submitted before they are sent to the server.
    long
    getBatchTimeout()
    Get the maximum time to wait before the next batch of tasks is to be sent for execution.
    ExecutorServiceConfiguration
    getConfiguration()
    Get the configuration for this executor service.
    <T> List<Future<T>>
    invokeAll(Collection<? extends Callable<T>> tasks)
    Executes the given tasks, returning a list of Futures holding their status and results when all complete.
    <T> List<Future<T>>
    invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
    Executes the given tasks, returning a list of Futures holding their status and results when all complete or the timeout expires, whichever happens first.
    <T> T
    invokeAny(Collection<? extends Callable<T>> tasks)
    Executes the given tasks, returning the result of one that has completed successfully (i.e., without throwing an exception), if any do.
    <T> T
    invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
    Executes the given tasks, returning the result of one that has completed successfully (i.e., without throwing an exception), if any do before the given timeout elapses.
    boolean
    isShutdown()
    Determine whether this executor has been shut down.
    boolean
    isTerminated()
    Determine whether all tasks have completed following shut down.
    void
    jobReturned(JobEvent event)
    Called when all results from a job have been received.
    ExecutorServiceConfiguration
    resetConfiguration()
    Reset the configuration for this executor service to a blank state.
    JPPFExecutorService
    setBatchSize(int batchSize)
    Set the minimum number of tasks that must be submitted before they are sent to the server.
    JPPFExecutorService
    setBatchTimeout(long batchTimeout)
    Set the maximum time to wait before the next batch of tasks is to be sent for execution.
    void
    shutdown()
    Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.
    List<Runnable>
    shutdownNow()
    Attempts to stop all actively executing tasks, halts the processing of waiting tasks, and returns a list of the tasks that were awaiting execution.
    This implementation simply waits for all submitted tasks to terminate, due to the complexity of stopping remote tasks.
    Future<?>
    submit(Runnable task)
    Submits a Runnable task for execution and returns a Future representing that task.
    <T> Future<T>
    submit(Runnable task, T result)
    Submits a Runnable task for execution and returns a Future representing that task that will upon completion return the given result.
    <T> Future<T>
    submit(Callable<T> task)
    Submit a value-returning task for execution and returns a Future representing the pending results of the task.

    Methods inherited from class org.jppf.client.event.JobListenerAdapter

    jobDispatched, jobEnded, jobStarted

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • JPPFExecutorService

      public JPPFExecutorService(JPPFClient client)
      Initialize this executor service with the specified JPPF client.
      Parameters:
      client - the JPPFClient to use for job submission.

    • JPPFExecutorService

      public JPPFExecutorService(JPPFClient client, int batchSize, long batchTimeout)
      Initialize this executor service with the specified JPPF client, batch size and batch tiemout.
      Parameters:
      client - the JPPFClient to use for job submission.
      batchSize - the minimum number of tasks that must be submitted before they are sent to the server.
      batchTimeout - the maximum time to wait before the next batch of tasks is to be sent for execution.

  • Method Details

    • invokeAll

      public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) throws InterruptedException
      Executes the given tasks, returning a list of Futures holding their status and results when all complete.
      Specified by:
      invokeAll in interface ExecutorService
      Type Parameters:
      T - the type of results returned by the tasks.
      Parameters:
      tasks - the tasks to execute.
      Returns:
      a list of Futures representing the tasks, in the same sequential order as produced by the iterator for the given task list, each of which has completed.
      Throws:
      InterruptedException - if interrupted while waiting, in which case unfinished tasks are cancelled.
      NullPointerException - if tasks or any of its elements are null.
      RejectedExecutionException - if any task cannot be scheduled for execution.

    • invokeAll

      public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) throws InterruptedException
      Executes the given tasks, returning a list of Futures holding their status and results when all complete or the timeout expires, whichever happens first.
      Specified by:
      invokeAll in interface ExecutorService
      Type Parameters:
      T - the type of results returned by the tasks.
      Parameters:
      tasks - the tasks to execute.
      timeout - the maximum time to wait.
      unit - the time unit of the timeout argument.
      Returns:
      a list of Futures representing the tasks, in the same sequential order as produced by the iterator for the given task list, each of which has completed.
      Throws:
      InterruptedException - if interrupted while waiting, in which case unfinished tasks are cancelled.
      NullPointerException - if tasks or any of its elements are null.
      RejectedExecutionException - if any task cannot be scheduled for execution.

    • invokeAny

      public <T> T invokeAny(Collection<? extends Callable<T>> tasks) throws InterruptedException, ExecutionException
      Executes the given tasks, returning the result of one that has completed successfully (i.e., without throwing an exception), if any do. Upon normal or exceptional return, tasks that have not completed are cancelled.
      Specified by:
      invokeAny in interface ExecutorService
      Type Parameters:
      T - the type of results returned by the tasks.
      Parameters:
      tasks - the tasks to execute.
      Returns:
      the result returned by one of the tasks.
      Throws:
      InterruptedException - if interrupted while waiting.
      NullPointerException - if tasks or any of its elements are null.
      IllegalArgumentException - if tasks empty.
      ExecutionException - if no task successfully completes.
      RejectedExecutionException - if tasks cannot be scheduled for execution.

    • invokeAny

      public <T> T invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
      Executes the given tasks, returning the result of one that has completed successfully (i.e., without throwing an exception), if any do before the given timeout elapses. Upon normal or exceptional return, tasks that have not completed are cancelled.
      Specified by:
      invokeAny in interface ExecutorService
      Type Parameters:
      T - the type of results returned by the tasks.
      Parameters:
      tasks - the tasks to execute.
      timeout - the maximum time to wait.
      unit - the time unit of the timeout argument.
      Returns:
      the result returned by one of the tasks.
      Throws:
      InterruptedException - if interrupted while waiting.
      NullPointerException - if tasks or any of its elements are null.
      IllegalArgumentException - if tasks empty.
      ExecutionException - if no task successfully completes.
      RejectedExecutionException - if tasks cannot be scheduled for execution.
      TimeoutException - if the given timeout elapses before any task successfully completes.

    • submit

      public <T> Future<T> submit(Callable<T> task)
      Submit a value-returning task for execution and returns a Future representing the pending results of the task.
      Specified by:
      submit in interface ExecutorService
      Type Parameters:
      T - the type of result returned by the task.
      Parameters:
      task - the task to execute.
      Returns:
      a Future representing pending completion of the task.

    • submit

      public Future<?> submit(Runnable task)
      Submits a Runnable task for execution and returns a Future representing that task.
      Specified by:
      submit in interface ExecutorService
      Parameters:
      task - the task to execute.
      See Also:

    • submit

      public <T> Future<T> submit(Runnable task, T result)
      Submits a Runnable task for execution and returns a Future representing that task that will upon completion return the given result.
      Specified by:
      submit in interface ExecutorService
      Type Parameters:
      T - the type of result returned by the task.
      Parameters:
      task - the task to execute.
      result - the result to return .
      Returns:
      a Future representing pending completion of the task, and whose get() method will return the given result upon completion.

    • execute

      public void execute(Runnable command)
      Executes the given command at some time in the future. The command may execute in a new thread, in a pooled thread, or in the calling thread, at the discretion of the Executor implementation.
      Specified by:
      execute in interface Executor
      Parameters:
      command - the command to execute.
      See Also:

    • awaitTermination

      public boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException
      Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
      Specified by:
      awaitTermination in interface ExecutorService
      Parameters:
      timeout - the maximum time to wait.
      unit - the time unit of the timeout argument.
      Returns:
      true if this executor terminated and false if the timeout elapsed before termination.
      Throws:
      InterruptedException - if interrupted while waiting.

    • isShutdown

      public boolean isShutdown()
      Determine whether this executor has been shut down.
      Specified by:
      isShutdown in interface ExecutorService
      Returns:
      true if this executor has been shut down, false otherwise.

    • isTerminated

      public boolean isTerminated()
      Determine whether all tasks have completed following shut down. Note that isTerminated is never true unless either shutdown or shutdownNow was called first.
      Specified by:
      isTerminated in interface ExecutorService
      Returns:
      true if all tasks have completed following shut down.

    • shutdown

      public void shutdown()
      Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.
      Specified by:
      shutdown in interface ExecutorService

    • shutdownNow

      public List<Runnable> shutdownNow()
      Attempts to stop all actively executing tasks, halts the processing of waiting tasks, and returns a list of the tasks that were awaiting execution.
      This implementation simply waits for all submitted tasks to terminate, due to the complexity of stopping remote tasks.
      Specified by:
      shutdownNow in interface ExecutorService
      Returns:
      a list of tasks that never commenced execution.

    • jobReturned

      public void jobReturned(JobEvent event)
      Called when all results from a job have been received.
      Specified by:
      jobReturned in interface JobListener
      Overrides:
      jobReturned in class JobListenerAdapter
      Parameters:
      event - the event object.

    • getBatchSize

      public int getBatchSize()
      Get the minimum number of tasks that must be submitted before they are sent to the server.
      Returns:
      the batch size as an int.

    • setBatchSize

      public JPPFExecutorService setBatchSize(int batchSize)
      Set the minimum number of tasks that must be submitted before they are sent to the server.
      Parameters:
      batchSize - the batch size as an int.
      Returns:
      this executor service, for method chaining.

    • getBatchTimeout

      public long getBatchTimeout()
      Get the maximum time to wait before the next batch of tasks is to be sent for execution.
      Returns:
      the timeout as a long.

    • setBatchTimeout

      public JPPFExecutorService setBatchTimeout(long batchTimeout)
      Set the maximum time to wait before the next batch of tasks is to be sent for execution.
      Parameters:
      batchTimeout - the timeout as a long.
      Returns:
      this executor service, for method chaining.

    • getConfiguration

      public ExecutorServiceConfiguration getConfiguration()
      Get the configuration for this executor service.
      Returns:
      an ExecutorServiceConfiguration instance.

    • resetConfiguration

      public ExecutorServiceConfiguration resetConfiguration()
      Reset the configuration for this executor service to a blank state.
      Returns:
      an ExecutorServiceConfiguration instance.