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

See Also:

JPPFExecutorService.setBatchSize(int), JPPFExecutorService.setBatchTimeout(long)

Constructor Summary

Constructors

Constructor and 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 and 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.
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.
<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.
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.

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

jobDispatched, jobEnded, jobReturned, jobStarted

Methods inherited from class java.lang.Object

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

Constructor Detail

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 Detail

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:

ExecutorService.submit(java.lang.Runnable)

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:

Executor.execute(java.lang.Runnable)

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.

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.