JSR166y Updates

BlenderRev generated at Wed Aug 18 12:18:58 2010
/export/Scratch/chris/repos/tl/jsr166yUpdates/build/solaris-sparc/docs/api generated at Wed Aug 18 12:18:31 2010
/export/Scratch/chris/repos/tl/master/build/solaris-sparc/docs/api generated at Fri Aug 13 16:30:35 2010

java.util.concurrent (1 interface, 2 classes, 20 methods)

ForkJoinPool ForkJoinPool.ManagedBlocker ForkJoinTask

java.util.concurrent.ForkJoinPool.ManagedBlocker

ForkJoinPool.ManagedBlocker.CLASS_COMMENT

java.util.concurrent
Interface ForkJoinPool.ManagedBlocker

Enclosing class:
ForkJoinPool

public static interface ForkJoinPool.ManagedBlocker

Interface for extending managed parallelism for tasks running in ForkJoinPool s.

A ManagedBlocker provides two methods. Method isReleasable must return true if blocking is not necessary. Method block blocks the current thread if necessary (perhaps internally invoking isReleasable before actually blocking). The unusual methods in this API accommodate synchronizers that may, but don't usually, block for long periods. Similarly, they allow more efficient internal handling of cases in which additional workers may be, but usually are not, needed to ensure sufficient parallelism. Toward this end, implementations of method isReleasable must be amenable to repeated invocation.

For example, here is a ManagedBlocker based on a ReentrantLock:

 class ManagedLocker implements ManagedBlocker {
   final ReentrantLock lock;
   boolean hasLock = false;
   ManagedLocker(ReentrantLock lock) { this.lock = lock; }
   public boolean block() {
     if (!hasLock)
       lock.lock();
     return true;
   }
   public boolean isReleasable() {
     return hasLock || (hasLock = lock.tryLock());
   }
 }

Here is a class that possibly blocks waiting for an item on a given queue:

 class QueueTaker<E> implements ManagedBlocker {
 final BlockingQueue<E> queue;
 volatile E item = null;
 QueueTaker(BlockingQueue<E> q) { this.queue = q; }
 public boolean block() throws InterruptedException {
 if (item == null)
 item = queue.take
 return true;
 }
 public boolean isReleasable() {
 return item != null || (item = queue.poll) != null;
 }
 public E getItem() { // call after pool.managedBlock completes
 return item;
 }
 } 

java.util.concurrent
Interface ForkJoinPool.ManagedBlocker

Enclosing class:
ForkJoinPool

public static interface ForkJoinPool.ManagedBlocker

Interface for extending managed parallelism for tasks running in ForkJoinPools.

A ManagedBlocker provides two methods. Method isReleasable must return true if blocking is not necessary. Method block blocks the current thread if necessary (perhaps internally invoking isReleasable before actually blocking).

For example, here is a ManagedBlocker based on a ReentrantLock:

 class ManagedLocker implements ManagedBlocker {
   final ReentrantLock lock;
   boolean hasLock = false;
   ManagedLocker(ReentrantLock lock) { this.lock = lock; }
   public boolean block() {
     if (!hasLock)
       lock.lock();
     return true;
   }
   public boolean isReleasable() {
     return hasLock || (hasLock = lock.tryLock());
   }
 }

java.util.concurrent
Interface ForkJoinPool.ManagedBlocker

Enclosing class:
ForkJoinPool

public static interface ForkJoinPool.ManagedBlocker

Interface for extending managed parallelism for tasks running in ForkJoinPools.

A ManagedBlocker provides two methods. Method isReleasable must return true if blocking is not necessary. Method block blocks the current thread if necessary (perhaps internally invoking isReleasable before actually blocking). The unusual methods in this API accommodate synchronizers that may, but don't usually, block for long periods. Similarly, they allow more efficient internal handling of cases in which additional workers may be, but usually are not, needed to ensure sufficient parallelism. Toward this end, implementations of method isReleasable must be amenable to repeated invocation.

For example, here is a ManagedBlocker based on a ReentrantLock:

 class ManagedLocker implements ManagedBlocker {
   final ReentrantLock lock;
   boolean hasLock = false;
   ManagedLocker(ReentrantLock lock) { this.lock = lock; }
   public boolean block() {
     if (!hasLock)
       lock.lock();
     return true;
   }
   public boolean isReleasable() {
     return hasLock || (hasLock = lock.tryLock());
   }
 }

Here is a class that possibly blocks waiting for an item on a given queue:

 class QueueTaker<E> implements ManagedBlocker {
   final BlockingQueue<E> queue;
   volatile E item = null;
   QueueTaker(BlockingQueue<E> q) { this.queue = q; }
   public boolean block() throws InterruptedException {
     if (item == null)
       item = queue.take
     return true;
   }
   public boolean isReleasable() {
     return item != null || (item = queue.poll) != null;
   }
   public E getItem() { // call after pool.managedBlock completes
     return item;
   }
 }

java.util.concurrent.ForkJoinPool (16 methods)

ForkJoinPool(int, java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory)
ForkJoinPool(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory)
getMaintainsParallelism()
getMaximumPoolSize()
managedBlock(java.util.concurrent.ForkJoinPool.ManagedBlocker, boolean)
setAsyncMode(boolean)
setMaintainsParallelism(boolean)
setMaximumPoolSize(int)
setParallelism(int)
setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler)
CLASS_COMMENT
ForkJoinPool()
ForkJoinPool(int)
ForkJoinPool(int, java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory, java.lang.Thread.UncaughtExceptionHandler, boolean)
getAsyncMode()
getRunningThreadCount()
managedBlock(java.util.concurrent.ForkJoinPool.ManagedBlocker)

ForkJoinPool.ForkJoinPool(int, java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory) (Deleted)

ForkJoinPool

public ForkJoinPool(int parallelism,
                    ForkJoinPool.ForkJoinWorkerThreadFactory factory)
Creates a ForkJoinPool with the given parallelism and thread factory.

Parameters:
parallelism - the parallelism level
factory - the factory for creating new threads
Throws:
IllegalArgumentException - if parallelism less than or equal to zero, or greater than implementation limit
NullPointerException - if the factory is null
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.ForkJoinPool(java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory) (Deleted)

ForkJoinPool

public ForkJoinPool(ForkJoinPool.ForkJoinWorkerThreadFactory factory)
Creates a ForkJoinPool with parallelism equal to Runtime.availableProcessors(), and using the given thread factory.

Parameters:
factory - the factory for creating new threads
Throws:
NullPointerException - if the factory is null
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.getMaintainsParallelism() (Deleted)

getMaintainsParallelism

public boolean getMaintainsParallelism()
Returns true if this pool dynamically maintains its target parallelism level. If false, new threads are added only to avoid possible starvation. This setting is by default true.

Returns:
true if maintains parallelism

ForkJoinPool.getMaximumPoolSize() (Deleted)

getMaximumPoolSize

public int getMaximumPoolSize()
Returns the maximum number of threads allowed to exist in the pool. Unless set using setMaximumPoolSize(int), the maximum is an implementation-defined value designed only to prevent runaway growth.

Returns:
the maximum

ForkJoinPool.managedBlock(java.util.concurrent.ForkJoinPool.ManagedBlocker, boolean) (Deleted)

managedBlock

public static void managedBlock(ForkJoinPool.ManagedBlocker blocker,
                                boolean maintainParallelism)
                         throws InterruptedException
Blocks in accord with the given blocker. If the current thread is a ForkJoinWorkerThread, this method possibly arranges for a spare thread to be activated if necessary to ensure parallelism while the current thread is blocked.

If maintainParallelism is true and the pool supports it (getMaintainsParallelism()), this method attempts to maintain the pool's nominal parallelism. Otherwise it activates a thread only if necessary to avoid complete starvation. This option may be preferable when blockages use timeouts, or are almost always brief.

If the caller is not a ForkJoinTask, this method is behaviorally equivalent to

 while (!blocker.isReleasable())
   if (blocker.block())
     return;
 
If the caller is a ForkJoinTask, then the pool may first be expanded to ensure parallelism, and later adjusted.

Parameters:
blocker - the blocker
maintainParallelism - if true and supported by this pool, attempt to maintain the pool's nominal parallelism; otherwise activate a thread only if necessary to avoid complete starvation.
Throws:
InterruptedException - if blocker.block did so

ForkJoinPool.setAsyncMode(boolean) (Deleted)

setAsyncMode

public boolean setAsyncMode(boolean async)
Establishes local first-in-first-out scheduling mode for forked tasks that are never joined. This mode may be more appropriate than default locally stack-based mode in applications in which worker threads only process asynchronous tasks. This method is designed to be invoked only when the pool is quiescent, and typically only before any tasks are submitted. The effects of invocations at other times may be unpredictable.

Parameters:
async - if true, use locally FIFO scheduling
Returns:
the previous mode
See Also:
getAsyncMode()

ForkJoinPool.setMaintainsParallelism(boolean) (Deleted)

setMaintainsParallelism

public void setMaintainsParallelism(boolean enable)
Sets whether this pool dynamically maintains its target parallelism level. If false, new threads are added only to avoid possible starvation.

Parameters:
enable - true to maintain parallelism

ForkJoinPool.setMaximumPoolSize(int) (Deleted)

setMaximumPoolSize

public void setMaximumPoolSize(int newMax)
Sets the maximum number of threads allowed to exist in the pool. The given value should normally be greater than or equal to the parallelism level. Setting this value has no effect on current pool size. It controls construction of new threads.

Throws:
IllegalArgumentException - if negative or greater than internal implementation limit

ForkJoinPool.setParallelism(int) (Deleted)

setParallelism

public void setParallelism(int parallelism)
Sets the target parallelism level of this pool.

Parameters:
parallelism - the target parallelism
Throws:
IllegalArgumentException - if parallelism less than or equal to zero or greater than maximum size bounds
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler) (Deleted)

setUncaughtExceptionHandler

public Thread.UncaughtExceptionHandler setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler h)
Sets the handler for internal worker threads that terminate due to unrecoverable errors encountered while executing tasks. Unless set, the current default or ThreadGroup handler is used as handler.

Parameters:
h - the new handler
Returns:
the old handler, or null if none
Throws:
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.CLASS_COMMENT

java.util.concurrent
Class ForkJoinPool


 java.lang.Object
  extended by java.util.concurrent.AbstractExecutorService
      extended by java.util.concurrent.ForkJoinPool
 
All Implemented Interfaces:
Executor , ExecutorService

public class ForkJoinPool
 extends AbstractExecutorService

An ExecutorService for running ForkJoinTask s. A ForkJoinPool provides the entry point for submissions from non- ForkJoinTask clients, s, as well as management and monitoring operations.

A ForkJoinPool differs from other kinds of ExecutorService mainly by virtue of employing work-stealing : all threads in the pool attempt to find and execute subtasks created by other active tasks (eventually blocking waiting for work if none exist). This enables efficient processing when most tasks spawn other subtasks (as do most ForkJoinTask s). When setting asyncMode to true in constructors, A ForkJoinPool s may also be appropriate for use with event-style tasks that are never joined.

A may also be used for mixed execution of some plain ForkJoinPool Runnable is constructed with a given target parallelism level; by default, equal to the number of available processors. The pool attempts to maintain enough active (or available) threads by dynamically adding, suspending, or resuming internal worker threads, even if some tasks are stalled waiting to join others. However, no such adjustments are guaranteed in the face of blocked IO or other unmanaged synchronization. The nested ForkJoinPool.ManagedBlocker interface enables extension of the kinds of synchronization accommodated.

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. Also, method toString() returns indications of pool state in a convenient form for informal monitoring.

As is the case with other ExecutorServices, there are three main task execution methods summarized in the following table. These are designed to be used by clients not already engaged in fork/join computations in the current pool. The main forms of these methods accept instances of - or Callable - based activities along with ForkJoinTask , but overloaded forms also allow mixed execution of plain s. When setting async mode , a Runnable ForkJoinPool - or may also be appropriate for use with fine-grained tasks of any form that are never joined. Otherwise, other Callable ExecutorService - based activities as well. However, tasks that are already executing in a pool should normally NOT use these pool execution methods, but instead use the within-computation forms listed in the table. implementations are typically more appropriate choices.

Call from non-fork/join clients Call from within fork/join computations
Arange async execution execute(ForkJoinTask) ForkJoinTask.fork()
Await and obtain result invoke(ForkJoinTask) ForkJoinTask.invoke()
Arrange exec and obtain Future submit(ForkJoinTask) ForkJoinTask.fork() are Futures)

A ForkJoinPool is constructed with a given target parallelism level; by default, equal to the number of available processors. Unless configured otherwise via setMaintainsParallelism(boolean) , the pool attempts to maintain this number of active (or available) threads by dynamically adding, suspending, or resuming internal worker threads, even if some tasks are stalled waiting to join others. However, no such adjustments are performed in the face of blocked IO or other unmanaged synchronization. The nested ForkJoinPool.ManagedBlocker interface enables extension of the kinds of synchronization accommodated. The target parallelism level may also be changed dynamically ( setParallelism(int) ). The total number of threads may be limited using method setMaximumPoolSize(int) , in which case it may become possible for the activities of a pool to stall due to the lack of available threads to process new tasks.

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. Also, method toString() returns indications of pool state in a convenient form for informal monitoring.

Sample Usage. Normally a single ForkJoinPool is used for all parallel task execution in a program or subsystem. Otherwise, use would not usually outweigh the construction and bookkeeping overhead of creating a large set of threads. For example, a common pool could be used for the SortTasks illustrated in RecursiveAction . Because ForkJoinPool uses threads in daemon mode, there is typically no need to explicitly shutdown() such a pool upon program exit.


 static final ForkJoinPool mainPool = new ForkJoinPool();
 ...
 public void sort(long[] array) {
   mainPool.invoke(new SortTask(array, 0, array.length));
 }
 

Implementation notes : This implementation restricts the maximum number of running threads to 32767. Attempts to create pools with greater than the maximum number result in IllegalArgumentException .

This implementation rejects submitted tasks (that is, by throwing RejectedExecutionException ) only when the pool is shut down or internal resources have been exhausted. down.

Since:
1.7

java.util.concurrent
Class ForkJoinPool

java.lang.Object
  extended by java.util.concurrent.AbstractExecutorService
      extended by java.util.concurrent.ForkJoinPool
All Implemented Interfaces:
Executor, ExecutorService

public class ForkJoinPool
extends AbstractExecutorService

An ExecutorService for running ForkJoinTasks. A ForkJoinPool provides the entry point for submissions from non-ForkJoinTasks, as well as management and monitoring operations.

A ForkJoinPool differs from other kinds of ExecutorService mainly by virtue of employing work-stealing: all threads in the pool attempt to find and execute subtasks created by other active tasks (eventually blocking waiting for work if none exist). This enables efficient processing when most tasks spawn other subtasks (as do most ForkJoinTasks). A ForkJoinPool may also be used for mixed execution of some plain Runnable- or Callable- based activities along with ForkJoinTasks. When setting async mode, a ForkJoinPool may also be appropriate for use with fine-grained tasks of any form that are never joined. Otherwise, other ExecutorService implementations are typically more appropriate choices.

A ForkJoinPool is constructed with a given target parallelism level; by default, equal to the number of available processors. Unless configured otherwise via setMaintainsParallelism(boolean), the pool attempts to maintain this number of active (or available) threads by dynamically adding, suspending, or resuming internal worker threads, even if some tasks are stalled waiting to join others. However, no such adjustments are performed in the face of blocked IO or other unmanaged synchronization. The nested ForkJoinPool.ManagedBlocker interface enables extension of the kinds of synchronization accommodated. The target parallelism level may also be changed dynamically (setParallelism(int)). The total number of threads may be limited using method setMaximumPoolSize(int), in which case it may become possible for the activities of a pool to stall due to the lack of available threads to process new tasks.

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. Also, method toString() returns indications of pool state in a convenient form for informal monitoring.

Sample Usage. Normally a single ForkJoinPool is used for all parallel task execution in a program or subsystem. Otherwise, use would not usually outweigh the construction and bookkeeping overhead of creating a large set of threads. For example, a common pool could be used for the SortTasks illustrated in RecursiveAction. Because ForkJoinPool uses threads in daemon mode, there is typically no need to explicitly shutdown() such a pool upon program exit.

 static final ForkJoinPool mainPool = new ForkJoinPool();
 ...
 public void sort(long[] array) {
   mainPool.invoke(new SortTask(array, 0, array.length));
 }
 

Implementation notes: This implementation restricts the maximum number of running threads to 32767. Attempts to create pools with greater than the maximum number result in IllegalArgumentException.

This implementation rejects submitted tasks (that is, by throwing RejectedExecutionException) only when the pool is shut down.

Since:
1.7

java.util.concurrent
Class ForkJoinPool

java.lang.Object
  extended by java.util.concurrent.AbstractExecutorService
      extended by java.util.concurrent.ForkJoinPool
All Implemented Interfaces:
Executor, ExecutorService

public class ForkJoinPool
extends AbstractExecutorService

An ExecutorService for running ForkJoinTasks. A ForkJoinPool provides the entry point for submissions from non-ForkJoinTask clients, as well as management and monitoring operations.

A ForkJoinPool differs from other kinds of ExecutorService mainly by virtue of employing work-stealing: all threads in the pool attempt to find and execute subtasks created by other active tasks (eventually blocking waiting for work if none exist). This enables efficient processing when most tasks spawn other subtasks (as do most ForkJoinTasks). When setting asyncMode to true in constructors, ForkJoinPools may also be appropriate for use with event-style tasks that are never joined.

A ForkJoinPool is constructed with a given target parallelism level; by default, equal to the number of available processors. The pool attempts to maintain enough active (or available) threads by dynamically adding, suspending, or resuming internal worker threads, even if some tasks are stalled waiting to join others. However, no such adjustments are guaranteed in the face of blocked IO or other unmanaged synchronization. The nested ForkJoinPool.ManagedBlocker interface enables extension of the kinds of synchronization accommodated.

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. Also, method toString() returns indications of pool state in a convenient form for informal monitoring.

As is the case with other ExecutorServices, there are three main task execution methods summarized in the following table. These are designed to be used by clients not already engaged in fork/join computations in the current pool. The main forms of these methods accept instances of ForkJoinTask, but overloaded forms also allow mixed execution of plain Runnable- or Callable- based activities as well. However, tasks that are already executing in a pool should normally NOT use these pool execution methods, but instead use the within-computation forms listed in the table.

Call from non-fork/join clients Call from within fork/join computations
Arange async execution execute(ForkJoinTask) ForkJoinTask.fork()
Await and obtain result invoke(ForkJoinTask) ForkJoinTask.invoke()
Arrange exec and obtain Future submit(ForkJoinTask) ForkJoinTask.fork() (ForkJoinTasks are Futures)

Sample Usage. Normally a single ForkJoinPool is used for all parallel task execution in a program or subsystem. Otherwise, use would not usually outweigh the construction and bookkeeping overhead of creating a large set of threads. For example, a common pool could be used for the SortTasks illustrated in RecursiveAction. Because ForkJoinPool uses threads in daemon mode, there is typically no need to explicitly shutdown() such a pool upon program exit.

 static final ForkJoinPool mainPool = new ForkJoinPool();
 ...
 public void sort(long[] array) {
   mainPool.invoke(new SortTask(array, 0, array.length));
 }
 

Implementation notes: This implementation restricts the maximum number of running threads to 32767. Attempts to create pools with greater than the maximum number result in IllegalArgumentException.

This implementation rejects submitted tasks (that is, by throwing RejectedExecutionException) only when the pool is shut down or internal resources have been exhausted.

Since:
1.7

ForkJoinPool.ForkJoinPool()

ForkJoinPool


 public ForkJoinPool()
Creates a ForkJoinPool with parallelism equal to Runtime.availableProcessors() , and using the default thread factory , no UncaughtExceptionHandler, and non-async LIFO processing mode. .

Throws:
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission ("modifyThread")

ForkJoinPool

public ForkJoinPool()
Creates a ForkJoinPool with parallelism equal to Runtime.availableProcessors(), and using the default thread factory.

Throws:
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool

public ForkJoinPool()
Creates a ForkJoinPool with parallelism equal to Runtime.availableProcessors(), using the default thread factory, no UncaughtExceptionHandler, and non-async LIFO processing mode.

Throws:
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.ForkJoinPool(int)

ForkJoinPool


 public ForkJoinPool(int parallelism)
Creates a ForkJoinPool with the indicated parallelism level, level and using the default thread factory , no UncaughtExceptionHandler, and non-async LIFO processing mode. .

Parameters:
parallelism - the parallelism level
Throws:
IllegalArgumentException - if parallelism less than or equal to zero, or greater than implementation limit
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission ("modifyThread")

ForkJoinPool

public ForkJoinPool(int parallelism)
Creates a ForkJoinPool with the indicated parallelism level and using the default thread factory.

Parameters:
parallelism - the parallelism level
Throws:
IllegalArgumentException - if parallelism less than or equal to zero, or greater than implementation limit
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool

public ForkJoinPool(int parallelism)
Creates a ForkJoinPool with the indicated parallelism level, the default thread factory, no UncaughtExceptionHandler, and non-async LIFO processing mode.

Parameters:
parallelism - the parallelism level
Throws:
IllegalArgumentException - if parallelism less than or equal to zero, or greater than implementation limit
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.ForkJoinPool(int, java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory, java.lang.Thread.UncaughtExceptionHandler, boolean) (New)

ForkJoinPool

public ForkJoinPool(int parallelism,
                    ForkJoinPool.ForkJoinWorkerThreadFactory factory,
                    Thread.UncaughtExceptionHandler handler,
                    boolean asyncMode)
Creates a ForkJoinPool with the given parameters.

Parameters:
parallelism - the parallelism level. For default value, use Runtime.availableProcessors().
factory - the factory for creating new threads. For default value, use defaultForkJoinWorkerThreadFactory.
handler - the handler for internal worker threads that terminate due to unrecoverable errors encountered while executing tasks. For default value, use null.
asyncMode - if true, establishes local first-in-first-out scheduling mode for forked tasks that are never joined. This mode may be more appropriate than default locally stack-based mode in applications in which worker threads only process event-style asynchronous tasks. For default value, use false.
Throws:
IllegalArgumentException - if parallelism less than or equal to zero, or greater than implementation limit
NullPointerException - if the factory is null
SecurityException - if a security manager exists and the caller is not permitted to modify threads because it does not hold RuntimePermission("modifyThread")

ForkJoinPool.getAsyncMode()

getAsyncMode


 public boolean getAsyncMode()
Returns true if this pool uses local first-in-first-out scheduling mode for forked tasks that are never joined.

Returns:
true if this pool uses async mode
See Also:
setAsyncMode(boolean)

getAsyncMode

public boolean getAsyncMode()
Returns true if this pool uses local first-in-first-out scheduling mode for forked tasks that are never joined.

Returns:
true if this pool uses async mode
See Also:
setAsyncMode(boolean)

getAsyncMode

public boolean getAsyncMode()
Returns true if this pool uses local first-in-first-out scheduling mode for forked tasks that are never joined.

Returns:
true if this pool uses async mode

ForkJoinPool.getRunningThreadCount()

getRunningThreadCount


 public int getRunningThreadCount()
Returns an estimate of the number of worker threads that are not blocked waiting to join tasks or for other managed synchronization. This method may overestimate the number of running threads.

Returns:
the number of worker threads

getRunningThreadCount

public int getRunningThreadCount()
Returns an estimate of the number of worker threads that are not blocked waiting to join tasks or for other managed synchronization.

Returns:
the number of worker threads

getRunningThreadCount

public int getRunningThreadCount()
Returns an estimate of the number of worker threads that are not blocked waiting to join tasks or for other managed synchronization. This method may overestimate the number of running threads.

Returns:
the number of worker threads

ForkJoinPool.managedBlock(java.util.concurrent.ForkJoinPool.ManagedBlocker) (New)

managedBlock

public static void managedBlock(ForkJoinPool.ManagedBlocker blocker)
                         throws InterruptedException
Blocks in accord with the given blocker. If the current thread is a ForkJoinWorkerThread, this method possibly arranges for a spare thread to be activated if necessary to ensure sufficient parallelism while the current thread is blocked.

If the caller is not a ForkJoinTask, this method is behaviorally equivalent to

 while (!blocker.isReleasable())
   if (blocker.block())
     return;
 
If the caller is a ForkJoinTask, then the pool may first be expanded to ensure parallelism, and later adjusted.

Parameters:
blocker - the blocker
Throws:
InterruptedException - if blocker.block did so

java.util.concurrent.ForkJoinTask (4 methods)

helpJoin()
quietlyHelpJoin()
CLASS_COMMENT
quietlyInvoke()
quietlyJoin()

ForkJoinTask.helpJoin() (Deleted)

helpJoin

public final V helpJoin()
Possibly executes other tasks until this task is done, then returns the result of the computation. This method may be more efficient than join, but is only applicable when there are no potential dependencies between continuation of the current task and that of any other task that might be executed while helping. (This usually holds for pure divide-and-conquer tasks).

This method may be invoked only from within ForkJoinTask computations (as may be determined using method inForkJoinPool()). Attempts to invoke in other contexts result in exceptions or errors, possibly including ClassCastException.

Returns:
the computed result

ForkJoinTask.quietlyHelpJoin() (Deleted)

quietlyHelpJoin

public final void quietlyHelpJoin()
Possibly executes other tasks until this task is done. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

This method may be invoked only from within ForkJoinTask computations (as may be determined using method inForkJoinPool()). Attempts to invoke in other contexts result in exceptions or errors, possibly including ClassCastException.

ForkJoinTask.CLASS_COMMENT

java.util.concurrent
Class ForkJoinTask<V>


 java.lang.Object
  extended by java.util.concurrent.ForkJoinTask<V>
 
All Implemented Interfaces:
java.io.Serializable, Future<V>
Direct Known Subclasses:
RecursiveAction , RecursiveTask

public abstract class ForkJoinTask<V>
 extends Object
 implements Future<V>, java.io.Serializable

Abstract base class for tasks that run within a ForkJoinPool . A ForkJoinTask is a thread-like entity that is much lighter weight than a normal thread. Huge numbers of tasks and subtasks may be hosted by a small number of actual threads in a ForkJoinPool, at the price of some usage limitations.

A "main" ForkJoinTask begins execution when submitted to a ForkJoinPool . Once started, it will usually in turn start other subtasks. As indicated by the name of this class, many programs using ForkJoinTask employ only methods fork() and join() , or derivatives such as invokeAll(java.util.concurrent.ForkJoinTask , java.util.concurrent.ForkJoinTask ) . However, this class also provides a number of other methods that can come into play in advanced usages, as well as extension mechanics that allow support of new forms of fork/join processing.

A ForkJoinTask is a lightweight form of Future . The efficiency of ForkJoinTask s stems from a set of restrictions (that are only partially statically enforceable) reflecting their intended use as computational tasks calculating pure functions or operating on purely isolated objects. The primary coordination mechanisms are fork() , that arranges asynchronous execution, and join() , that doesn't proceed until the task's result has been computed. Computations should avoid synchronized methods or blocks, and should minimize other blocking synchronization apart from joining other tasks or using synchronizers such as Phasers that are advertised to cooperate with fork/join scheduling. Tasks should also not perform blocking IO, and should ideally access variables that are completely independent of those accessed by other running tasks. Minor breaches of these restrictions, for example using shared output streams, may be tolerable in practice, but frequent use may result in poor performance, and the potential to indefinitely stall if the number of threads not waiting for IO or other external synchronization becomes exhausted. This usage restriction is in part enforced by not permitting checked exceptions such as IOExceptions to be thrown. However, computations may still encounter unchecked exceptions, that are rethrown to callers attempting to join them. These exceptions may additionally include RejectedExecutionException stemming from internal resource exhaustion, such as failure to allocate internal task queues.

The primary method for awaiting completion and extracting results of a task is join() , but there are several variants: The Future.get() methods support interruptible and/or timed waits for completion and report results using Future conventions. Method invoke() helpJoin() enables callers to actively execute other tasks while awaiting joins, which is sometimes more efficient but only applies when all subtasks are known to be strictly tree-structured. Method invoke() is semantically equivalent to fork(); join() but always attempts to begin execution in the current thread. The " quiet " forms of these methods do not extract results or report exceptions. These may be useful when a set of tasks are being executed, and you need to delay processing of results or exceptions until all complete. Method invokeAll (available in multiple versions) performs the most common form of parallel invocation: forking a set of tasks and joining them all.

The execution status of tasks may be queried at several levels of detail: isDone() is true if a task completed in any way (including the case where a task was cancelled without executing); isCompletedNormally() is true if a task completed without cancellation or encountering an exception; isCancelled() is true if the task was cancelled (in which case getException() returns a CancellationException ); and isCompletedAbnormally() is true if a task was either cancelled or encountered an exception, in which case getException() will return either the encountered exception or CancellationException .

The ForkJoinTask class is not usually directly subclassed. Instead, you subclass one of the abstract classes that support a particular style of fork/join processing, typically RecursiveAction for computations that do not return results, or RecursiveTask for those that do. Normally, a concrete ForkJoinTask subclass declares fields comprising its parameters, established in a constructor, and then defines a compute method that somehow uses the control methods supplied by this base class. While these methods have public access (to allow instances of different task subclasses to call each other's methods), some of them may only be called from within other ForkJoinTasks (as may be determined using method inForkJoinPool() ). Attempts to invoke them in other contexts result in exceptions or errors, possibly including ClassCastException.

Most base support methods are final , to prevent overriding of implementations that are intrinsically tied to the underlying lightweight task scheduling framework. Developers creating new basic styles of fork/join processing should minimally implement protected methods exec() , setRawResult(V) , and getRawResult() , while also introducing an abstract computational method that can be implemented in its subclasses, possibly relying on other protected methods provided by this class.

ForkJoinTasks should perform relatively small amounts of computation. Large tasks should be split into smaller subtasks, usually via recursive decomposition. As a very rough rule of thumb, a task should perform more than 100 and less than 10000 basic computational steps. If tasks are too big, then parallelism cannot improve throughput. If too small, then memory and internal task maintenance overhead may overwhelm processing.

This class provides adapt methods for Runnable and Callable , that may be of use when mixing execution of ForkJoinTasks with other kinds of tasks. When all tasks are of this form, consider using a pool constructed in asyncMode async mode.

ForkJoinTasks are Serializable , which enables them to be used in extensions such as remote execution frameworks. It is sensible to serialize tasks only before or after, but not during, execution. Serialization is not relied on during execution itself.

Since:
1.7
See Also:
Serialized Form

java.util.concurrent
Class ForkJoinTask<V>

java.lang.Object
  extended by java.util.concurrent.ForkJoinTask<V>
All Implemented Interfaces:
java.io.Serializable, Future<V>
Direct Known Subclasses:
RecursiveAction, RecursiveTask

public abstract class ForkJoinTask<V>
extends Object
implements Future<V>, java.io.Serializable

Abstract base class for tasks that run within a ForkJoinPool. A ForkJoinTask is a thread-like entity that is much lighter weight than a normal thread. Huge numbers of tasks and subtasks may be hosted by a small number of actual threads in a ForkJoinPool, at the price of some usage limitations.

A "main" ForkJoinTask begins execution when submitted to a ForkJoinPool. Once started, it will usually in turn start other subtasks. As indicated by the name of this class, many programs using ForkJoinTask employ only methods fork() and join(), or derivatives such as invokeAll(java.util.concurrent.ForkJoinTask, java.util.concurrent.ForkJoinTask). However, this class also provides a number of other methods that can come into play in advanced usages, as well as extension mechanics that allow support of new forms of fork/join processing.

A ForkJoinTask is a lightweight form of Future. The efficiency of ForkJoinTasks stems from a set of restrictions (that are only partially statically enforceable) reflecting their intended use as computational tasks calculating pure functions or operating on purely isolated objects. The primary coordination mechanisms are fork(), that arranges asynchronous execution, and join(), that doesn't proceed until the task's result has been computed. Computations should avoid synchronized methods or blocks, and should minimize other blocking synchronization apart from joining other tasks or using synchronizers such as Phasers that are advertised to cooperate with fork/join scheduling. Tasks should also not perform blocking IO, and should ideally access variables that are completely independent of those accessed by other running tasks. Minor breaches of these restrictions, for example using shared output streams, may be tolerable in practice, but frequent use may result in poor performance, and the potential to indefinitely stall if the number of threads not waiting for IO or other external synchronization becomes exhausted. This usage restriction is in part enforced by not permitting checked exceptions such as IOExceptions to be thrown. However, computations may still encounter unchecked exceptions, that are rethrown to callers attempting to join them. These exceptions may additionally include RejectedExecutionException stemming from internal resource exhaustion, such as failure to allocate internal task queues.

The primary method for awaiting completion and extracting results of a task is join(), but there are several variants: The Future.get() methods support interruptible and/or timed waits for completion and report results using Future conventions. Method helpJoin() enables callers to actively execute other tasks while awaiting joins, which is sometimes more efficient but only applies when all subtasks are known to be strictly tree-structured. Method invoke() is semantically equivalent to fork(); join() but always attempts to begin execution in the current thread. The "quiet" forms of these methods do not extract results or report exceptions. These may be useful when a set of tasks are being executed, and you need to delay processing of results or exceptions until all complete. Method invokeAll (available in multiple versions) performs the most common form of parallel invocation: forking a set of tasks and joining them all.

The execution status of tasks may be queried at several levels of detail: isDone() is true if a task completed in any way (including the case where a task was cancelled without executing); isCompletedNormally() is true if a task completed without cancellation or encountering an exception; isCancelled() is true if the task was cancelled (in which case getException() returns a CancellationException); and isCompletedAbnormally() is true if a task was either cancelled or encountered an exception, in which case getException() will return either the encountered exception or CancellationException.

The ForkJoinTask class is not usually directly subclassed. Instead, you subclass one of the abstract classes that support a particular style of fork/join processing, typically RecursiveAction for computations that do not return results, or RecursiveTask for those that do. Normally, a concrete ForkJoinTask subclass declares fields comprising its parameters, established in a constructor, and then defines a compute method that somehow uses the control methods supplied by this base class. While these methods have public access (to allow instances of different task subclasses to call each other's methods), some of them may only be called from within other ForkJoinTasks (as may be determined using method inForkJoinPool()). Attempts to invoke them in other contexts result in exceptions or errors, possibly including ClassCastException.

Most base support methods are final, to prevent overriding of implementations that are intrinsically tied to the underlying lightweight task scheduling framework. Developers creating new basic styles of fork/join processing should minimally implement protected methods exec(), setRawResult(V), and getRawResult(), while also introducing an abstract computational method that can be implemented in its subclasses, possibly relying on other protected methods provided by this class.

ForkJoinTasks should perform relatively small amounts of computation. Large tasks should be split into smaller subtasks, usually via recursive decomposition. As a very rough rule of thumb, a task should perform more than 100 and less than 10000 basic computational steps. If tasks are too big, then parallelism cannot improve throughput. If too small, then memory and internal task maintenance overhead may overwhelm processing.

This class provides adapt methods for Runnable and Callable, that may be of use when mixing execution of ForkJoinTasks with other kinds of tasks. When all tasks are of this form, consider using a pool in async mode.

ForkJoinTasks are Serializable, which enables them to be used in extensions such as remote execution frameworks. It is sensible to serialize tasks only before or after, but not during, execution. Serialization is not relied on during execution itself.

Since:
1.7
See Also:
Serialized Form

java.util.concurrent
Class ForkJoinTask<V>

java.lang.Object
  extended by java.util.concurrent.ForkJoinTask<V>
All Implemented Interfaces:
java.io.Serializable, Future<V>
Direct Known Subclasses:
RecursiveAction, RecursiveTask

public abstract class ForkJoinTask<V>
extends Object
implements Future<V>, java.io.Serializable

Abstract base class for tasks that run within a ForkJoinPool. A ForkJoinTask is a thread-like entity that is much lighter weight than a normal thread. Huge numbers of tasks and subtasks may be hosted by a small number of actual threads in a ForkJoinPool, at the price of some usage limitations.

A "main" ForkJoinTask begins execution when submitted to a ForkJoinPool. Once started, it will usually in turn start other subtasks. As indicated by the name of this class, many programs using ForkJoinTask employ only methods fork() and join(), or derivatives such as invokeAll(java.util.concurrent.ForkJoinTask, java.util.concurrent.ForkJoinTask). However, this class also provides a number of other methods that can come into play in advanced usages, as well as extension mechanics that allow support of new forms of fork/join processing.

A ForkJoinTask is a lightweight form of Future. The efficiency of ForkJoinTasks stems from a set of restrictions (that are only partially statically enforceable) reflecting their intended use as computational tasks calculating pure functions or operating on purely isolated objects. The primary coordination mechanisms are fork(), that arranges asynchronous execution, and join(), that doesn't proceed until the task's result has been computed. Computations should avoid synchronized methods or blocks, and should minimize other blocking synchronization apart from joining other tasks or using synchronizers such as Phasers that are advertised to cooperate with fork/join scheduling. Tasks should also not perform blocking IO, and should ideally access variables that are completely independent of those accessed by other running tasks. Minor breaches of these restrictions, for example using shared output streams, may be tolerable in practice, but frequent use may result in poor performance, and the potential to indefinitely stall if the number of threads not waiting for IO or other external synchronization becomes exhausted. This usage restriction is in part enforced by not permitting checked exceptions such as IOExceptions to be thrown. However, computations may still encounter unchecked exceptions, that are rethrown to callers attempting to join them. These exceptions may additionally include RejectedExecutionException stemming from internal resource exhaustion, such as failure to allocate internal task queues.

The primary method for awaiting completion and extracting results of a task is join(), but there are several variants: The Future.get() methods support interruptible and/or timed waits for completion and report results using Future conventions. Method invoke() is semantically equivalent to fork(); join() but always attempts to begin execution in the current thread. The "quiet" forms of these methods do not extract results or report exceptions. These may be useful when a set of tasks are being executed, and you need to delay processing of results or exceptions until all complete. Method invokeAll (available in multiple versions) performs the most common form of parallel invocation: forking a set of tasks and joining them all.

The execution status of tasks may be queried at several levels of detail: isDone() is true if a task completed in any way (including the case where a task was cancelled without executing); isCompletedNormally() is true if a task completed without cancellation or encountering an exception; isCancelled() is true if the task was cancelled (in which case getException() returns a CancellationException); and isCompletedAbnormally() is true if a task was either cancelled or encountered an exception, in which case getException() will return either the encountered exception or CancellationException.

The ForkJoinTask class is not usually directly subclassed. Instead, you subclass one of the abstract classes that support a particular style of fork/join processing, typically RecursiveAction for computations that do not return results, or RecursiveTask for those that do. Normally, a concrete ForkJoinTask subclass declares fields comprising its parameters, established in a constructor, and then defines a compute method that somehow uses the control methods supplied by this base class. While these methods have public access (to allow instances of different task subclasses to call each other's methods), some of them may only be called from within other ForkJoinTasks (as may be determined using method inForkJoinPool()). Attempts to invoke them in other contexts result in exceptions or errors, possibly including ClassCastException.

Most base support methods are final, to prevent overriding of implementations that are intrinsically tied to the underlying lightweight task scheduling framework. Developers creating new basic styles of fork/join processing should minimally implement protected methods exec(), setRawResult(V), and getRawResult(), while also introducing an abstract computational method that can be implemented in its subclasses, possibly relying on other protected methods provided by this class.

ForkJoinTasks should perform relatively small amounts of computation. Large tasks should be split into smaller subtasks, usually via recursive decomposition. As a very rough rule of thumb, a task should perform more than 100 and less than 10000 basic computational steps. If tasks are too big, then parallelism cannot improve throughput. If too small, then memory and internal task maintenance overhead may overwhelm processing.

This class provides adapt methods for Runnable and Callable, that may be of use when mixing execution of ForkJoinTasks with other kinds of tasks. When all tasks are of this form, consider using a pool constructed in asyncMode.

ForkJoinTasks are Serializable, which enables them to be used in extensions such as remote execution frameworks. It is sensible to serialize tasks only before or after, but not during, execution. Serialization is not relied on during execution itself.

Since:
1.7
See Also:
Serialized Form

ForkJoinTask.quietlyInvoke()

quietlyInvoke


 public final void quietlyInvoke()
Commences performing this task and awaits its completion if necessary, without returning its result or throwing its an exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

quietlyInvoke

public final void quietlyInvoke()
Commences performing this task and awaits its completion if necessary, without returning its result or throwing an exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

quietlyInvoke

public final void quietlyInvoke()
Commences performing this task and awaits its completion if necessary, without returning its result or throwing its exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

ForkJoinTask.quietlyJoin()

quietlyJoin


 public final void quietlyJoin()
Joins this task, without returning its result or throwing its an exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

quietlyJoin

public final void quietlyJoin()
Joins this task, without returning its result or throwing an exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

quietlyJoin

public final void quietlyJoin()
Joins this task, without returning its result or throwing its exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.