jsr166z.forkjoin
Class ForkJoinWorkerThread

java.lang.Object
  java.lang.Thread
      jsr166z.forkjoin.ForkJoinWorkerThread

All Implemented Interfaces:

java.lang.Runnable

public class ForkJoinWorkerThread
extends java.lang.Thread

A thread that is internally managed by a ForkJoinPool to execute ForkJoinTasks. This class additionally provides public static methods accessing some basic scheduling and execution mechanics for the current ForkJoinWorkerThread. These methods may be invoked only from within other ForkJoinTask computations. Attempts to invoke in other contexts result in exceptions or errors including ClassCastException. These methods enable construction of special-purpose task classes, as well as specialized idioms occasionally useful in ForkJoinTask processing.

The form of supported static methods reflects the fact that worker threads may access and process tasks obtained in any of three ways. In preference order: Local tasks are processed in LIFO (newest first) order. Stolen tasks are obtained from other threads in FIFO (oldest first) order, only if there are no local tasks to run. Submissions form a FIFO queue common to the entire pool, and are started only if no other work is available.

This class is subclassable solely for the sake of adding functionality -- there are no overridable methods dealing with scheduling or execution. However, you can override initialization and termination cleanup methods surrounding the main task processing loop. If you do create such a subclass, you will also need to supply a custom ForkJoinWorkerThreadFactory to use it in a ForkJoinPool.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

protected

ForkJoinWorkerThread(ForkJoinPool pool) Creates a ForkJoinWorkerThread operating in the given pool.

Method Summary

static boolean	executeLocalTask() Execute the next task locally queued by the current worker, if one is available.
static boolean	executeTask() Helps this program complete by processing a local, stolen or submitted task, if one is available.
static int	getEstimatedSurplusTaskCount() Returns an estimate of how many more locally queued tasks there are than idle worker threads that might steal them.
static int	getLocalQueueSize() Returns the number of tasks waiting to be run by the current worker thread.
static ForkJoinPool	getPool() Returns the pool hosting the current task execution.
static int	getPoolIndex() Returns the index number of the current worker thread in its pool.
static double	nextRandomDouble() Returns a random double using a per-worker random number generator with the same properties as Random.nextDouble()
static int	nextRandomInt() Returns a random integer using a per-worker random number generator with the same properties as Random.nextInt()
static int	nextRandomInt(int n) Returns a random integer using a per-worker random number generator with the same properties as Random.nextInt(int)
static long	nextRandomLong() Returns a random long using a per-worker random number generator with the same properties as Random.nextLong()
static long	nextRandomLong(long n) Returns a random integer using a per-worker random number generator with the same properties as Random.nextInt(int)
protected void	onStart() Initializes internal state after construction but before processing any tasks.
protected void	onTermination(java.lang.Throwable exception) Perform cleanup associated with termination of this worker thread.
static ForkJoinTask<?>	peekLocalTask() Returns, but does not remove or execute, the next task locally queued for execution by the current worker thread.
static ForkJoinTask<?>	pollLocalTask() Removes and returns, without executing, the next task queued for execution in the current worker thread's local queue.
static ForkJoinTask<?>	pollTask() Removes and returns, without executing, the next task available for execution by the current worker thread, which may be a locally queued task, one stolen from another worker, or a pool submission.
static boolean	removeIfNextLocalTask(ForkJoinTask<?> task) Removes and returns, without executing, the given task from the queue hosting current execution only if it would be the next task executed by the current worker.
void	run() This method is required to be public, but should never be called explicitly.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Constructor Detail

ForkJoinWorkerThread

protected ForkJoinWorkerThread(ForkJoinPool pool)

Creates a ForkJoinWorkerThread operating in the given pool.

Parameters:

pool - the pool this thread works in

Throws:

java.lang.NullPointerException - if pool is null;

Method Detail

run

public void run()

This method is required to be public, but should never be called explicitly. It executes the main run loop to execute ForkJoinTasks.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

onStart

protected void onStart()

Initializes internal state after construction but before processing any tasks. If you override this method, you must invoke super.onStart() at the beginning of the method. Initialization requires care: Most fields must have legal default values, to ensure that attempted accesses from other threads work correctly even before this thread starts processing tasks.

onTermination

protected void onTermination(java.lang.Throwable exception)

Perform cleanup associated with termination of this worker thread. If you override this method, you must invoke super.onTermination at the end of the overridden method.

Parameters:

exception - the exception causing this thread to abort due to an unrecoverable error, or null if completed normally.

getPool

public static ForkJoinPool getPool()

Returns the pool hosting the current task execution.

Returns:

the pool

getPoolIndex

public static int getPoolIndex()

Returns the index number of the current worker thread in its pool. The return value is in the range 0...getPool().getPoolSize()-1. This method may be useful for applications that track status or collect results per-worker rather than per-task.

Returns:

the index number.

getLocalQueueSize

public static int getLocalQueueSize()

Returns the number of tasks waiting to be run by the current worker thread. This value may be useful for heuristic decisions about whether to fork other tasks.

Returns:

the number of tasks

getEstimatedSurplusTaskCount

public static int getEstimatedSurplusTaskCount()

Returns an estimate of how many more locally queued tasks there are than idle worker threads that might steal them. This value may be useful for heuristic decisions about whether to fork other tasks.

Returns:

the number of tasks, which is negative if there are fewer tasks than idle workers

peekLocalTask

public static ForkJoinTask<?> peekLocalTask()

Returns, but does not remove or execute, the next task locally queued for execution by the current worker thread. There is no guarantee that this task will be the next one actually returned or executed from other polling or execution methods.

Returns:

the next task or null if none

pollLocalTask

public static ForkJoinTask<?> pollLocalTask()

Removes and returns, without executing, the next task queued for execution in the current worker thread's local queue.

Returns:

the next task to execute, or null if none

removeIfNextLocalTask

public static boolean removeIfNextLocalTask(ForkJoinTask<?> task)

Removes and returns, without executing, the given task from the queue hosting current execution only if it would be the next task executed by the current worker. Among other usages, this method may be used to bypass task execution during cancellation.

Parameters:

task - the task

Returns:

true if removed

executeLocalTask

public static boolean executeLocalTask()

Execute the next task locally queued by the current worker, if one is available.

Returns:

true if a task was run; a false return indicates that no task was available.

pollTask

public static ForkJoinTask<?> pollTask()

Removes and returns, without executing, the next task available for execution by the current worker thread, which may be a locally queued task, one stolen from another worker, or a pool submission.

Returns:

the next task to execute, or null if none

executeTask

public static boolean executeTask()

Helps this program complete by processing a local, stolen or submitted task, if one is available. This method may be useful when several tasks are forked, and only one of them must be joined, as in:

   while (!t1.isDone() && !t2.isDone()) 
     ForkJoinWorkerThread.executeTask();
 

Similarly, you can help process tasks until all computations complete via

   while(ForkJoinWorkerThread.executeTask() || 
         !ForkJoinWorkerThread.getPool().isQuiescent()) 
      ;
 

Returns:

true if a task was run; a false return indicates that no task was available.

nextRandomInt

public static int nextRandomInt()

Returns a random integer using a per-worker random number generator with the same properties as Random.nextInt()

Returns:

the next pseudorandom, uniformly distributed int value from this worker's random number generator's sequence

nextRandomInt

public static int nextRandomInt(int n)

Returns a random integer using a per-worker random number generator with the same properties as Random.nextInt(int)

Parameters:

n - the bound on the random number to be returned. Must be positive.

Returns:

the next pseudorandom, uniformly distributed int value between 0 (inclusive) and n (exclusive) from this worker's random number generator's sequence

Throws:

java.lang.IllegalArgumentException - if n is not positive

nextRandomLong

public static long nextRandomLong()

Returns a random long using a per-worker random number generator with the same properties as Random.nextLong()

Returns:

the next pseudorandom, uniformly distributed long value from this worker's random number generator's sequence

nextRandomLong

public static long nextRandomLong(long n)

Returns a random integer using a per-worker random number generator with the same properties as Random.nextInt(int)

Parameters:

n - the bound on the random number to be returned. Must be positive.

Returns:

the next pseudorandom, uniformly distributed int value between 0 (inclusive) and n (exclusive) from this worker's random number generator's sequence

Throws:

java.lang.IllegalArgumentException - if n is not positive

nextRandomDouble

public static double nextRandomDouble()

Returns a random double using a per-worker random number generator with the same properties as Random.nextDouble()

Returns:

the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this worker's random number generator's sequence