net.sf.mybatchfwk
Class PausableThreadPoolExecutor

java.lang.Object
  java.util.concurrent.AbstractExecutorService
      net.sf.mybatchfwk.PausableThreadPoolExecutor

All Implemented Interfaces:

java.util.concurrent.Executor, java.util.concurrent.ExecutorService, ITaskExecutor

public class PausableThreadPoolExecutor
extends java.util.concurrent.AbstractExecutorService
implements ITaskExecutor

The thread pool executor service that executes the tasks

Author:

Jérôme Bertèche (cyberteche@users.sourceforge.net)

Field Summary

protected BatchService	batchService
protected int	corePoolSize Core pool size, updated only while holding mainLock, but volatile to allow concurrent readability even during updates.
protected int	poolSize Current pool size, updated only while holding mainLock but volatile to allow concurrent readability even during updates.
protected static int	RUNNING Normal, not-shutdown mode
protected int	runState Lifecycle state
protected static int	SHUTDOWN Controlled shutdown mode
protected static int	STOP Immediate shutdown mode
protected static int	TERMINATED Final state
protected java.util.concurrent.BlockingQueue<java.lang.Runnable>	workQueue Queue used for holding tasks and handing off to worker threads.

Constructor Summary

PausableThreadPoolExecutor(BatchService batchService, int corePoolSize, int maximumPoolSize, long keepAliveTime, java.util.concurrent.TimeUnit unit, java.util.concurrent.BlockingQueue<java.lang.Runnable> workQueue)
Creates a new ThreadPoolExecutor with the given initial parameters and default thread factory and handler.

Method Summary

protected boolean	addIfUnderCorePoolSize(java.lang.Runnable firstTask) Create and start a new thread running firstTask as its first task, only if fewer than corePoolSize threads are running.
protected java.lang.Runnable	addIfUnderMaximumPoolSize(java.lang.Runnable firstTask) Create and start a new thread only if fewer than maximumPoolSize threads are running.
protected void	afterExecute(java.lang.Runnable r, java.lang.Throwable t) Method invoked upon completion of execution of the given Runnable.
boolean	awaitTermination(long timeout, java.util.concurrent.TimeUnit unit)
protected void	beforeExecute(java.lang.Thread t, java.lang.Runnable r) Method invoked prior to executing the given Runnable in the given thread.
boolean	execute(ITask task) Execute the given task, waiting for free space in blocking queue if necessary
void	execute(java.lang.Runnable command) Executes the given task sometime in the future.
protected void	finalize() Invokes shutdown when this executor is no longer referenced.
int	getActiveCount() Returns the approximate number of threads that are actively executing tasks.
long	getCompletedTaskCount() Returns the approximate total number of tasks that have completed execution.
int	getCorePoolSize() Returns the core number of threads.
long	getKeepAliveTime(java.util.concurrent.TimeUnit unit) Returns the thread keep-alive time, which is the amount of time which threads in excess of the core pool size may remain idle before being terminated.
int	getLargestPoolSize() Returns the largest number of threads that have ever simultaneously been in the pool.
int	getMaximumPoolSize() Returns the maximum allowed number of threads.
int	getPoolSize() Returns the current number of threads in the pool.
java.util.concurrent.BlockingQueue<java.lang.Runnable>	getQueue() Returns the task queue used by this executor.
long	getTaskCount() Returns the approximate total number of tasks that have been scheduled for execution.
java.util.concurrent.ThreadFactory	getThreadFactory() Returns the thread factory used to create new threads.
boolean	isRunning() Indicate the running state of the executor (the user can shutdown this service through JMX).
boolean	isShutdown()
boolean	isTerminated()
boolean	isTerminating() Returns true if this executor is in the process of terminating after shutdown or shutdownNow but has not completely terminated.
void	pause() Pause the execution of all tasks
int	prestartAllCoreThreads() Starts all core threads, causing them to idly wait for work.
boolean	prestartCoreThread() Starts a core thread, causing it to idly wait for work.
void	purge() Tries to remove from the work queue all Future tasks that have been cancelled.
boolean	remove(java.lang.Runnable task) Removes this task from the executor's internal queue if it is present, thus causing it not to be run if it has not already started.
void	resume() Resume the execution of all tasks
void	setCorePoolSize(int corePoolSize) Sets the core number of threads.
void	setKeepAliveTime(long time, java.util.concurrent.TimeUnit unit) Sets the time limit for which threads may remain idle before being terminated.
void	setMaximumPoolSize(int maximumPoolSize) Sets the maximum allowed number of threads.
void	setThreadFactory(java.util.concurrent.ThreadFactory threadFactory) Sets the thread factory used to create new threads.
void	shutdown() Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.
java.util.List<java.lang.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.
protected void	terminated() Method invoked when the Executor has terminated.

Methods inherited from class java.util.concurrent.AbstractExecutorService

invokeAll, invokeAll, invokeAny, invokeAny, submit, submit, submit

Methods inherited from class java.lang.Object

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

Field Detail

batchService

protected BatchService batchService

workQueue

protected final java.util.concurrent.BlockingQueue<java.lang.Runnable> workQueue

Queue used for holding tasks and handing off to worker threads.

corePoolSize

protected volatile int corePoolSize

Core pool size, updated only while holding mainLock, but volatile to allow concurrent readability even during updates.

poolSize

protected volatile int poolSize

Current pool size, updated only while holding mainLock but volatile to allow concurrent readability even during updates.

runState

protected volatile int runState

Lifecycle state

RUNNING

protected static final int RUNNING

Normal, not-shutdown mode

See Also:

Constant Field Values

SHUTDOWN

protected static final int SHUTDOWN

Controlled shutdown mode

See Also:

Constant Field Values

STOP

protected static final int STOP

Immediate shutdown mode

See Also:

Constant Field Values

TERMINATED

protected static final int TERMINATED

Final state

See Also:

Constant Field Values

Constructor Detail

PausableThreadPoolExecutor

public PausableThreadPoolExecutor(BatchService batchService,
                                  int corePoolSize,
                                  int maximumPoolSize,
                                  long keepAliveTime,
                                  java.util.concurrent.TimeUnit unit,
                                  java.util.concurrent.BlockingQueue<java.lang.Runnable> workQueue)

Creates a new ThreadPoolExecutor with the given initial parameters and default thread factory and handler. It may be more convenient to use one of the Executors factory methods instead of this general purpose constructor.

Parameters:

corePoolSize - the number of threads to keep in the pool, even if they are idle.

maximumPoolSize - the maximum number of threads to allow in the pool.

keepAliveTime - when the number of threads is greater than the core, this is the maximum time that excess idle threads will wait for new tasks before terminating.

unit - the time unit for the keepAliveTime argument.

workQueue - the queue to use for holding tasks before they are executed. This queue will hold only the Runnable tasks submitted by the execute method.

Throws:

java.lang.IllegalArgumentException - if corePoolSize, or keepAliveTime less than zero, or if maximumPoolSize less than or equal to zero, or if corePoolSize greater than maximumPoolSize.

java.lang.NullPointerException - if workQueue is null

Method Detail

addIfUnderCorePoolSize

protected boolean addIfUnderCorePoolSize(java.lang.Runnable firstTask)

Create and start a new thread running firstTask as its first task, only if fewer than corePoolSize threads are running.

Parameters:

firstTask - the task the new thread should run first (or null if none)

Returns:

true if successful.

addIfUnderMaximumPoolSize

protected java.lang.Runnable addIfUnderMaximumPoolSize(java.lang.Runnable firstTask)

Create and start a new thread only if fewer than maximumPoolSize threads are running. The new thread runs as its first task the next task in queue, or if there is none, the given task.

Parameters:

firstTask - the task the new thread should run first (or null if none)

Returns:

null on failure, else the first task to be run by new thread.

execute

public void execute(java.lang.Runnable command)

Executes the given task sometime in the future. The task may execute in a new thread or in an existing pooled thread. If the task cannot be submitted for execution, either because this executor has been shutdown or because its capacity has been reached, the task is handled by the current RejectedExecutionHandler.

Specified by:

execute in interface java.util.concurrent.Executor

Parameters:

command - the task to execute

Throws:

RejectedExecutionException - at discretion of RejectedExecutionHandler, if task cannot be accepted for execution

java.lang.NullPointerException - if command is null

execute

public boolean execute(ITask task)
                throws BatchException

Description copied from interface: ITaskExecutor

Execute the given task, waiting for free space in blocking queue if necessary

Specified by:

execute in interface ITaskExecutor

Parameters:

task - the task to execute

Returns:

true is the task has been added to the execution queue, false otherwise (the user can shutdown this service through JMX)

Throws:

BatchException

shutdown

public void shutdown()

Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted. Invocation has no additional effect if already shut down.

Specified by:

shutdown in interface java.util.concurrent.ExecutorService

Throws:

java.lang.SecurityException - if a security manager exists and shutting down this ExecutorService may manipulate threads that the caller is not permitted to modify because it does not hold RuntimePermission("modifyThread"), or the security manager's checkAccess method denies access.

shutdownNow

public java.util.List<java.lang.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 cancels tasks via Thread.interrupt(), so if any tasks mask or fail to respond to interrupts, they may never terminate.

Specified by:

shutdownNow in interface java.util.concurrent.ExecutorService

Returns:

list of tasks that never commenced execution

Throws:

java.lang.SecurityException - if a security manager exists and shutting down this ExecutorService may manipulate threads that the caller is not permitted to modify because it does not hold RuntimePermission("modifyThread"), or the security manager's checkAccess method denies access.

isShutdown

public boolean isShutdown()

Specified by:

isShutdown in interface java.util.concurrent.ExecutorService

isTerminating

public boolean isTerminating()

Returns true if this executor is in the process of terminating after shutdown or shutdownNow but has not completely terminated. This method may be useful for debugging. A return of true reported a sufficient period after shutdown may indicate that submitted tasks have ignored or suppressed interruption, causing this executor not to properly terminate.

Returns:

true if terminating but not yet terminated.

isTerminated

public boolean isTerminated()

Specified by:

isTerminated in interface java.util.concurrent.ExecutorService

awaitTermination

public boolean awaitTermination(long timeout,
                                java.util.concurrent.TimeUnit unit)
                         throws java.lang.InterruptedException

Specified by:

awaitTermination in interface java.util.concurrent.ExecutorService

Throws:

java.lang.InterruptedException

finalize

protected void finalize()

Invokes shutdown when this executor is no longer referenced.

Overrides:

finalize in class java.lang.Object

setThreadFactory

public void setThreadFactory(java.util.concurrent.ThreadFactory threadFactory)

Sets the thread factory used to create new threads.

Parameters:

threadFactory - the new thread factory

Throws:

java.lang.NullPointerException - if threadFactory is null

See Also:

getThreadFactory()

getThreadFactory

public java.util.concurrent.ThreadFactory getThreadFactory()

Returns the thread factory used to create new threads.

Returns:

the current thread factory

See Also:

setThreadFactory(java.util.concurrent.ThreadFactory)

getQueue

public java.util.concurrent.BlockingQueue<java.lang.Runnable> getQueue()

Returns the task queue used by this executor. Access to the task queue is intended primarily for debugging and monitoring. This queue may be in active use. Retrieving the task queue does not prevent queued tasks from executing.

Returns:

the task queue

remove

public boolean remove(java.lang.Runnable task)

Removes this task from the executor's internal queue if it is present, thus causing it not to be run if it has not already started.

This method may be useful as one part of a cancellation scheme. It may fail to remove tasks that have been converted into other forms before being placed on the internal queue. For example, a task entered using submit might be converted into a form that maintains Future status. However, in such cases, method ThreadPoolExecutor.purge() may be used to remove those Futures that have been cancelled.

Parameters:

task - the task to remove

Returns:

true if the task was removed

purge

public void purge()

Tries to remove from the work queue all Future tasks that have been cancelled. This method can be useful as a storage reclamation operation, that has no other impact on functionality. Cancelled tasks are never executed, but may accumulate in work queues until worker threads can actively remove them. Invoking this method instead tries to remove them now. However, this method may fail to remove tasks in the presence of interference by other threads.

setCorePoolSize

public void setCorePoolSize(int corePoolSize)

Sets the core number of threads. This overrides any value set in the constructor. If the new value is smaller than the current value, excess existing threads will be terminated when they next become idle. If larger, new threads will, if needed, be started to execute any queued tasks.

Parameters:

corePoolSize - the new core size

Throws:

java.lang.IllegalArgumentException - if corePoolSize less than zero

See Also:

getCorePoolSize()

getCorePoolSize

public int getCorePoolSize()

Returns the core number of threads.

Returns:

the core number of threads

See Also:

setCorePoolSize(int)

prestartCoreThread

public boolean prestartCoreThread()

Starts a core thread, causing it to idly wait for work. This overrides the default policy of starting core threads only when new tasks are executed. This method will return false if all core threads have already been started.

Returns:

true if a thread was started

prestartAllCoreThreads

public int prestartAllCoreThreads()

Starts all core threads, causing them to idly wait for work. This overrides the default policy of starting core threads only when new tasks are executed.

Returns:

the number of threads started.

setMaximumPoolSize

public void setMaximumPoolSize(int maximumPoolSize)

Sets the maximum allowed number of threads. This overrides any value set in the constructor. If the new value is smaller than the current value, excess existing threads will be terminated when they next become idle.

Parameters:

maximumPoolSize - the new maximum

Throws:

java.lang.IllegalArgumentException - if maximumPoolSize less than zero or the core pool size

See Also:

getMaximumPoolSize()

getMaximumPoolSize

public int getMaximumPoolSize()

Returns the maximum allowed number of threads.

Returns:

the maximum allowed number of threads

See Also:

setMaximumPoolSize(int)

setKeepAliveTime

public void setKeepAliveTime(long time,
                             java.util.concurrent.TimeUnit unit)

Sets the time limit for which threads may remain idle before being terminated. If there are more than the core number of threads currently in the pool, after waiting this amount of time without processing a task, excess threads will be terminated. This overrides any value set in the constructor.

Parameters:

time - the time to wait. A time value of zero will cause excess threads to terminate immediately after executing tasks.

unit - the time unit of the time argument

Throws:

java.lang.IllegalArgumentException - if time less than zero

See Also:

getKeepAliveTime(java.util.concurrent.TimeUnit)

getKeepAliveTime

public long getKeepAliveTime(java.util.concurrent.TimeUnit unit)

Returns the thread keep-alive time, which is the amount of time which threads in excess of the core pool size may remain idle before being terminated.

Parameters:

unit - the desired time unit of the result

Returns:

the time limit

See Also:

setKeepAliveTime(long, java.util.concurrent.TimeUnit)

getPoolSize

public int getPoolSize()

Returns the current number of threads in the pool.

Returns:

the number of threads

getActiveCount

public int getActiveCount()

Returns the approximate number of threads that are actively executing tasks.

Returns:

the number of threads

getLargestPoolSize

public int getLargestPoolSize()

Returns the largest number of threads that have ever simultaneously been in the pool.

Returns:

the number of threads

getTaskCount

public long getTaskCount()

Returns the approximate total number of tasks that have been scheduled for execution. Because the states of tasks and threads may change dynamically during computation, the returned value is only an approximation, but one that does not ever decrease across successive calls.

Specified by:

getTaskCount in interface ITaskExecutor

Returns:

the number of tasks

getCompletedTaskCount

public long getCompletedTaskCount()

Returns the approximate total number of tasks that have completed execution. Because the states of tasks and threads may change dynamically during computation, the returned value is only an approximation, but one that does not ever decrease across successive calls.

Returns:

the number of tasks

terminated

protected void terminated()

Method invoked when the Executor has terminated. Default implementation does nothing. Note: To properly nest multiple overridings, subclasses should generally invoke super.terminated within this method.

beforeExecute

protected void beforeExecute(java.lang.Thread t,
                             java.lang.Runnable r)

Method invoked prior to executing the given Runnable in the given thread. This method is invoked by thread t that will execute task r, and may be used to re-initialize ThreadLocals, or to perform logging. Note: To properly nest multiple overridings, subclasses should generally invoke super.beforeExecute at the end of this method.

Parameters:

t - the thread that will run task r.

r - the task that will be executed.

afterExecute

protected void afterExecute(java.lang.Runnable r,
                            java.lang.Throwable t)

Method invoked upon completion of execution of the given Runnable. This method is invoked by the thread that executed the task. If non-null, the Throwable is the uncaught exception that caused execution to terminate abruptly. Note: To properly nest multiple overridings, subclasses should generally invoke super.afterExecute at the beginning of this method.

Parameters:

r - the runnable that has completed.

t - the exception that caused termination, or null if execution completed normally.

pause

public void pause()

Pause the execution of all tasks

resume

public void resume()

Resume the execution of all tasks

isRunning

public boolean isRunning()

Description copied from interface: ITaskExecutor

Indicate the running state of the executor (the user can shutdown this service through JMX). If false, then no more task must be execute.

Specified by:

isRunning in interface ITaskExecutor

Returns:

true is the service is running, false otherwise