jsr166y.forkjoin
public class ForkJoinPool extends java.lang.Object implements ForkJoinExecutor
Class ForkJoinPool does not implement the ExecutorService interface because it only executes ForkJoinTasks, not arbitrary Runnables. However, for the sake of uniformity, it supports analogous lifecycle control methods such as shutdown.
A ForkJoinPool may be constructed with any number of worker threads, and worker threads may be added and removed dynamically. However, as a general rule, using a pool size of the number of processors on a given system (as arranged by the default constructor) will result in the best performance. Resizing may be expensive and may cause transient imbalances and slowdowns.
In addition to execution and lifecycle control methods, this class provides status check methods (for example getStealCount) that are intended to aid in developing, tuning, and monitoring fork/join applications.
Modifier and Type | Class and Description |
---|---|
static class |
ForkJoinPool.DefaultForkJoinWorkerThreadFactory
The default ForkJoinWorkerThreadFactory, used unless overridden
in ForkJoinPool constructors.
|
static interface |
ForkJoinPool.ForkJoinWorkerThreadFactory
Factory for creating new ForkJoinWorkerThreads.
|
Constructor and Description |
---|
ForkJoinPool()
Creates a ForkJoinPool with a pool size equal to the number of
processors available on the system and using the default
ForkJoinWorkerThreadFactory,
|
ForkJoinPool(ForkJoinPool.ForkJoinWorkerThreadFactory factory)
Creates a ForkJoinPool with a pool size equal to the number of
processors available on the system and using the given
ForkJoinWorkerThreadFactory,
|
ForkJoinPool(int poolSize)
Creates a ForkJoinPool with the indicated number of Worker
threads, and using the default ForkJoinWorkerThreadFactory,
|
ForkJoinPool(int poolSize,
ForkJoinPool.ForkJoinWorkerThreadFactory factory)
Creates a ForkJoinPool with the indicated number of worker
threads and the given factory.
|
Modifier and Type | Method and Description |
---|---|
int |
addWorkers(int numberToAdd)
Tries to adds the indicated number of new worker threads to the
pool.
|
boolean |
awaitTermination(long timeout,
java.util.concurrent.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.
|
<T> void |
execute(ForkJoinTask<T> task)
Arranges for (asynchronous) execution of the given task.
|
int |
getActiveSubmissionCount()
Returns the number of tasks that have been submitted (via
submit or invoke) and are currently executing
in the pool.
|
int |
getActiveThreadCount()
Returns the approximate number of threads that are
currently executing tasks.
|
ForkJoinPool.ForkJoinWorkerThreadFactory |
getFactory()
Returns the factory used for constructing new workers
|
int |
getIdleThreadCount()
Returns the approximate number of threads that are currently
idle waiting for tasks.
|
int |
getParallelismLevel()
Equivalent to
getPoolSize() . |
int |
getPoolSize()
Returns the targetted number of worker threads in this pool.
|
int |
getRunningWorkerCount()
Returns the number of worker threads that have started but not
yet terminated.
|
long |
getStealCount()
Returns the total number of tasks stolen from one thread's work
queue by another.
|
long |
getTotalPerThreadQueueSize()
Returns the total number of tasks currently held in queues by
worker threads (but not including tasks submitted to the pool
that have not begun executing).
|
java.lang.Thread.UncaughtExceptionHandler |
getUncaughtExceptionHandler()
Returns the handler for internal worker threads that terminate
due to unrecoverable errors encountered while executing tasks.
|
boolean |
hasQueuedSubmissions()
Returns true if there are any tasks submitted to this pool
that have not yet begun executing.
|
<T> T |
invoke(ForkJoinTask<T> task)
Performs the given task; returning its result upon completion
|
boolean |
isQuiescent()
Returns true if all worker threads are currently idle.
|
boolean |
isShutdown()
Returns true if this pool has been shut down.
|
boolean |
isTerminated()
Returns true if all tasks have completed following shut down.
|
boolean |
isTerminating()
Returns true if termination has commenced but has
not yet completed.
|
int |
removeWorkers(int numberToRemove)
Tries to remove the indicated number of worker threads from the
pool.
|
int |
setPoolSize(int newSize)
Tries to add or remove workers to attain the given pool size.
|
java.lang.Thread.UncaughtExceptionHandler |
setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler h)
Sets the handler for internal worker threads that terminate due
to unrecoverable errors encountered while executing tasks.
|
void |
shutdown()
Initiates an orderly shutdown in which previously submitted
tasks are executed, but no new tasks will be accepted.
|
void |
shutdownNow()
Attempts to stop all actively executing tasks, and cancels all
waiting tasks.
|
<T> java.util.concurrent.Future<T> |
submit(ForkJoinTask<T> task)
Arranges for (asynchronous) execution of the given task,
returning a Future that may be used to obtain results
upon completion.
|
public ForkJoinPool()
java.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public ForkJoinPool(int poolSize)
poolSize
- the number of worker threadsjava.lang.IllegalArgumentException
- if poolSize less than or
equal to zerojava.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public ForkJoinPool(ForkJoinPool.ForkJoinWorkerThreadFactory factory)
factory
- the factory for creating new threadsjava.lang.NullPointerException
- if factory is nulljava.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public ForkJoinPool(int poolSize, ForkJoinPool.ForkJoinWorkerThreadFactory factory)
You can also add and remove threads while the pool is running. But it is generally more efficient and leads to more predictable performance to initialize the pool with a sufficient number of threads to support the desired concurrency level and leave this value fixed.
poolSize
- the number of worker threadsfactory
- the factory for creating new threadsjava.lang.IllegalArgumentException
- if poolSize less than or
equal to zerojava.lang.NullPointerException
- if factory is nulljava.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public <T> T invoke(ForkJoinTask<T> task)
invoke
in interface ForkJoinExecutor
task
- the taskjava.lang.NullPointerException
- if task is nulljava.util.concurrent.RejectedExecutionException
- if pool is shut downpublic <T> java.util.concurrent.Future<T> submit(ForkJoinTask<T> task)
submit
in interface ForkJoinExecutor
task
- the taskjava.lang.NullPointerException
- if task is nulljava.util.concurrent.RejectedExecutionException
- if pool is shut downpublic <T> void execute(ForkJoinTask<T> task)
execute
in interface ForkJoinExecutor
task
- the taskjava.lang.NullPointerException
- if task is nulljava.util.concurrent.RejectedExecutionException
- if pool is shut downpublic int getPoolSize()
public int getParallelismLevel()
getPoolSize()
.getParallelismLevel
in interface ForkJoinExecutor
public int getRunningWorkerCount()
public java.lang.Thread.UncaughtExceptionHandler setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler h)
h
- the new handlerjava.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public java.lang.Thread.UncaughtExceptionHandler getUncaughtExceptionHandler()
public int addWorkers(int numberToAdd)
java.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public int removeWorkers(int numberToRemove)
java.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public int setPoolSize(int newSize)
newSize
- the target poolSizejava.lang.IllegalArgumentException
- if newSize less than or
equal to zerojava.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public void shutdown()
java.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public void shutdownNow()
java.lang.SecurityException
- if a security manager exists and
the caller is not permitted to modify threads
because it does not hold RuntimePermission
("modifyThread"),public boolean isShutdown()
public boolean isTerminated()
public boolean isTerminating()
public boolean awaitTermination(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException
timeout
- the maximum time to waitunit
- the time unit of the timeout argumentjava.lang.InterruptedException
- if interrupted while waitingpublic final boolean isQuiescent()
public int getActiveThreadCount()
public int getIdleThreadCount()
public long getStealCount()
public long getTotalPerThreadQueueSize()
public boolean hasQueuedSubmissions()
public int getActiveSubmissionCount()
public ForkJoinPool.ForkJoinWorkerThreadFactory getFactory()