ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/jsr166y/ForkJoinTask.java

Comparing jsr166/src/jsr166y/ForkJoinTask.java (file contents):
Revision 1.1 by dl, Tue Jan 6 14:30:31 2009 UTC vs.
Revision 1.2 by dl, Wed Jan 7 16:07:37 2009 UTC

#	Line 13 | Line 13 | import sun.misc.Unsafe;
13		import java.lang.reflect.*;
14
15		/**
16	<	* Abstract base class for tasks that run within a ForkJoinPool.  A
17	<	* ForkJoinTask is a thread-like entity that is much lighter weight
18	<	* than a normal thread.  Huge numbers of tasks and subtasks may be
19	<	* hosted by a small number of actual threads in a ForkJoinPool,
20	<	* at the price of some usage limitations.
21	<	*
22	<	* <p> ForkJoinTasks are forms of <tt>Futures</tt> supporting a
23	<	* limited range of use.  The "lightness" of ForkJoinTasks is due to a
24	<	* set of restrictions (that are only partially statically
25	<	* enforceable) reflecting their intended use as computational tasks
26	<	* calculating pure functions or operating on purely isolated objects.
27	<	* The primary coordination mechanisms supported for ForkJoinTasks are
28	<	* <tt>fork</tt>, that arranges asynchronous execution, and
29	<	* <tt>join</tt>, that doesn't proceed until the task's result has
30	<	* been computed. (Cancellation is also supported).  The computation
31	<	* defined in the <tt>compute</tt> method should avoid
32	<	* <tt>synchronized</tt> methods or blocks, and should minimize
33	<	* blocking synchronization apart from joining other tasks or using
16	>	* Abstract base class for tasks that run within a {@link
17	>	* ForkJoinPool}.  A ForkJoinTask is a thread-like entity that is much
18	>	* lighter weight than a normal thread.  Huge numbers of tasks and
19	>	* subtasks may be hosted by a small number of actual threads in a
20	>	* ForkJoinPool, at the price of some usage limitations.
21	>	*
22	>	* <p> A "main" ForkJoinTask begins execution when submitted to a
23	>	* {@link ForkJoinPool}. Once started, it will usually in turn start
24	>	* other subtasks.  As indicated by the name of this class, many
25	>	* programs using ForkJoinTasks employ only methods <code>fork</code>
26	>	* and <code>join</code>, or derivatives such as
27	>	* <code>invokeAll</code>.  However, this class also provides a number
28	>	* of other methods that can come into play in advanced usages, as
29	>	* well as extension mechanics that allow support of new forms of
30	>	* fork/join processing.
31	>	*
32	>	* <p>A ForkJoinTask is a lightweight form of {@link Future}.  The
33	>	* efficiency of ForkJoinTasks stems from a set of restrictions (that
34	>	* are only partially statically enforceable) reflecting their
35	>	* intended use as computational tasks calculating pure functions or
36	>	* operating on purely isolated objects.  The primary coordination
37	>	* mechanisms are {@link #fork}, that arranges asynchronous execution,
38	>	* and {@link #join}, that doesn't proceed until the task's result has
39	>	* been computed.  Computations should avoid <code>synchronized</code>
40	>	* methods or blocks, and should minimize other blocking
41	>	* synchronization apart from joining other tasks or using
42		* synchronizers such as Phasers that are advertised to cooperate with
43		* fork/join scheduling. Tasks should also not perform blocking IO,
44		* and should ideally access variables that are completely independent
#	Line 38 | Line 46 | import java.lang.reflect.*;
46		* restrictions, for example using shared output streams, may be
47		* tolerable in practice, but frequent use may result in poor
48		* performance, and the potential to indefinitely stall if the number
49	<	* of threads not waiting for external synchronization becomes
50	<	* exhausted. This usage restriction is in part enforced by not
51	<	* permitting checked exceptions such as IOExceptions to be
52	<	* thrown. However, computations may still encounter unchecked
49	>	* of threads not waiting for IO or other external synchronization
50	>	* becomes exhausted. This usage restriction is in part enforced by
51	>	* not permitting checked exceptions such as <code>IOExceptions</code>
52	>	* to be thrown. However, computations may still encounter unchecked
53		* exceptions, that are rethrown to callers attempting join
54		* them. These exceptions may additionally include
55		* RejectedExecutionExceptions stemming from internal resource
56		* exhaustion such as failure to allocate internal task queues.
57		*
58	<	* <p> The <tt>ForkJoinTask</tt> class is not usually directly
59	<	* subclassed.  Instead, you subclass one of the abstract classes that
60	<	* support different styles of fork/join processing.  Normally, a
61	<	* concrete ForkJoinTask subclass declares fields comprising its
62	<	* parameters, established in a constructor, and then defines a
63	<	* <tt>compute</tt> method that somehow uses the control methods
64	<	* supplied by this base class. While these methods have
65	<	* <tt>public</tt> access, some of them may only be called from within
66	<	* other ForkJoinTasks. Attempts to invoke them in other contexts
67	<	* result in exceptions or errors including ClassCastException.  The
68	<	* only way to invoke a "main" driver task is to submit it to a
69	<	* ForkJoinPool. Once started, this will usually in turn start other
70	<	* subtasks.
58	>	* <p>The primary method for awaiting completion and extracting
59	>	* results of a task is {@link #join}, but there are several variants:
60	>	* The {@link Future#get} methods support interruptible and/or timed
61	>	* waits for completion and report results using <code>Future</code>
62	>	* conventions. Method {@link #helpJoin} enables callers to actively
63	>	* execute other tasks while awaiting joins, which is sometimes more
64	>	* efficient but only applies when all subtasks are known to be
65	>	* strictly tree-structured. Method {@link #invoke} is semantically
66	>	* equivalent to <code>fork(); join()</code> but always attempts to
67	>	* begin execution in the current thread. The "<em>quiet</em>" forms
68	>	* of these methods do not extract results or report exceptions. These
69	>	* may be useful when a set of tasks are being executed, and you need
70	>	* to delay processing of results or exceptions until all complete.
71	>	* Method <code>invokeAll</code> (available in multiple versions)
72	>	* performs the most common form of parallel invocation: forking a set
73	>	* of tasks and joining them all.
74	>	*
75	>	* <p> The ForkJoinTask class is not usually directly subclassed.
76	>	* Instead, you subclass one of the abstract classes that support a
77	>	* particular style of fork/join processing.  Normally, a concrete
78	>	* ForkJoinTask subclass declares fields comprising its parameters,
79	>	* established in a constructor, and then defines a <code>compute</code>
80	>	* method that somehow uses the control methods supplied by this base
81	>	* class. While these methods have <code>public</code> access (to allow
82	>	* instances of different task subclasses to call each others
83	>	* methods), some of them may only be called from within other
84	>	* ForkJoinTasks. Attempts to invoke them in other contexts result in
85	>	* exceptions or errors including ClassCastException.
86		*
87	<	* <p>Most base support methods are <tt>final</tt> because their
87	>	* <p>Most base support methods are <code>final</code> because their
88		* implementations are intrinsically tied to the underlying
89		* lightweight task scheduling framework, and so cannot be overridden.
90		* Developers creating new basic styles of fork/join processing should
91	<	* minimally implement protected methods <tt>exec</tt>,
92	<	* <tt>setRawResult</tt>, and <tt>getRawResult</tt>, while also
93	<	* introducing an abstract computational method that can be
94	<	* implemented in its subclasses. To support such extensions,
95	<	* instances of ForkJoinTasks maintain an atomically updated
96	<	* <tt>short</tt> representing user-defined control state.  Control
74	<	* state is guaranteed initially to be zero, and to be negative upon
75	<	* completion, but may otherwise be used for any other control
76	<	* purposes, such as maintaining join counts.  The {@link
77	<	* ForkJoinWorkerThread} class supports additional inspection and
78	<	* tuning methods that can be useful when developing extensions.
91	>	* minimally implement <code>protected</code> methods
92	>	* <code>exec</code>, <code>setRawResult</code>, and
93	>	* <code>getRawResult</code>, while also introducing an abstract
94	>	* computational method that can be implemented in its subclasses,
95	>	* possibly relying on other <code>protected</code> methods provided
96	>	* by this class.
97		*
98		* <p>ForkJoinTasks should perform relatively small amounts of
99		* computations, othewise splitting into smaller tasks. As a very
#	Line 84 | Line 102 | import java.lang.reflect.*;
102		* parellelism cannot improve throughput. If too small, then memory
103		* and internal task maintenance overhead may overwhelm processing.
104		*
105	<	* <p>ForkJoinTasks are <tt>Serializable</tt>, which enables them to
106	<	* be used in extensions such as remote execution frameworks. However,
107	<	* it is in general safe to serialize tasks only before or after, but
105	>	* <p>ForkJoinTasks are <code>Serializable</code>, which enables them
106	>	* to be used in extensions such as remote execution frameworks. It is
107	>	* in general sensible to serialize tasks only before or after, but
108		* not during execution. Serialization is not relied on during
109		* execution itself.
110		*/
111		public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
112	+
113		/**
114	<	* Status field holding all run status. We pack this into a single
115	<	* int both to minimize footprint overhead and to ensure atomicity
116	<	* (updates are via CAS).
98	<	*
99	<	* Status is initially zero, and takes on nonnegative values until
114	>	* Run control status bits packed into a single int to minimize
115	>	* footprint and to ensure atomicity (via CAS).  Status is
116	>	* initially zero, and takes on nonnegative values until
117		* completed, upon which status holds COMPLETED. CANCELLED, or
118		* EXCEPTIONAL, which use the top 3 bits.  Tasks undergoing
119		* blocking waits by other threads have SIGNAL_MASK bits set --
#	Line 144 | Line 161 | public abstract class ForkJoinTask<V> im
161		(ForkJoinWorkerThread)t : null);
162		}
163
147	–	/**
148	–	* Get pool of current worker thread, or null if not a worker thread
149	–	*/
150	–	static ForkJoinPool getWorkerPool() {
151	–	Thread t = Thread.currentThread();
152	–	return ((t instanceof ForkJoinWorkerThread)?
153	–	((ForkJoinWorkerThread)t).pool : null);
154	–	}
155	–
164		final boolean casStatus(int cmp, int val) {
165		return _unsafe.compareAndSwapInt(this, statusOffset, cmp, val);
166		}
#	Line 172 | Line 180 | public abstract class ForkJoinTask<V> im
180		* @param completion one of NORMAL, CANCELLED, EXCEPTIONAL
181		*/
182		final void setCompletion(int completion) {
183	<	ForkJoinPool pool = getWorkerPool();
183	>	ForkJoinPool pool = getPool();
184		if (pool != null) {
185		int s; // Clear signal bits while setting completion status
186		do;while ((s = status) >= 0 && !casStatus(s, completion));
#	Line 314 | Line 322 | public abstract class ForkJoinTask<V> im
322		}
323		}
324
325	+	/**
326	+	* Handle interruptions during waits.
327	+	*/
328		private void onInterruptedWait() {
329	<	Thread t = Thread.currentThread();
330	<	if (t instanceof ForkJoinWorkerThread) {
331	<	ForkJoinWorkerThread w = (ForkJoinWorkerThread)t;
332	<	if (w.isTerminating())
333	<	cancelIgnoreExceptions();
334	<	}
324	<	else { // re-interrupt
325	<	try {
326	<	t.interrupt();
327	<	} catch (SecurityException ignore) {
328	<	}
329	<	}
329	>	ForkJoinWorkerThread w = getWorker();
330	>	if (w == null)
331	>	Thread.currentThread().interrupt(); // re-interrupt
332	>	else if (w.isTerminating())
333	>	cancelIgnoreExceptions();
334	>	// else if FJworker, ignore interrupt
335		}
336
337		// Recording and reporting exceptions
#	Line 457 | Line 462 | public abstract class ForkJoinTask<V> im
462		* Arranges to asynchronously execute this task.  While it is not
463		* necessarily enforced, it is a usage error to fork a task more
464		* than once unless it has completed and been reinitialized.  This
465	<	* method may be invoked only from within other ForkJoinTask
465	>	* method may be invoked only from within ForkJoinTask
466		* computations. Attempts to invoke in other contexts result in
467		* exceptions or errors including ClassCastException.
468		*/
#	Line 467 | Line 472 | public abstract class ForkJoinTask<V> im
472
473		/**
474		* Returns the result of the computation when it is ready.
475	<	* This method differs from <tt>get</tt> in that abnormal
475	>	* This method differs from <code>get</code> in that abnormal
476		* completion results in RuntimeExceptions or Errors, not
477		* ExecutionExceptions.
478		*
#	Line 496 | Line 501 | public abstract class ForkJoinTask<V> im
501		}
502
503		/**
504	<	* Possibly executes other tasks until this task is ready, then
505	<	* returns the result of the computation.  This method may be more
501	<	* efficient than <tt>join</tt>, but is only applicable when there
502	<	* are no potemtial dependencies between continuation of the
503	<	* current task and that of any other task that might be executed
504	<	* while helping. (This usually holds for pure divide-and-conquer
505	<	* tasks).
506	<	* @return the computed result
507	<	*/
508	<	public final V helpJoin() {
509	<	ForkJoinWorkerThread w = (ForkJoinWorkerThread)(Thread.currentThread());
510	<	if (status < 0 || !w.unpushTask(this) || !tryExec())
511	<	reportException(w.helpJoinTask(this));
512	<	return getRawResult();
513	<	}
514	<
515	<	/**
516	<	* Performs this task, awaits its completion if necessary, and
517	<	* return its result.
504	>	* Commences performing this task, awaits its completion if
505	>	* necessary, and return its result.
506		* @throws Throwable (a RuntimeException, Error, or unchecked
507		* exception) if the underlying computation did so.
508		* @return the computed result
#	Line 527 | Line 515 | public abstract class ForkJoinTask<V> im
515		}
516
517		/**
518	<	* Joins this task, without returning its result or throwing an
519	<	* exception. This method may be useful when processing
520	<	* collections of tasks when some have been cancelled or otherwise
521	<	* known to have aborted.
518	>	* Forks both tasks, returning when <code>isDone</code> holds for
519	>	* both of them or an exception is encountered. This method may be
520	>	* invoked only from within ForkJoinTask computations. Attempts to
521	>	* invoke in other contexts result in exceptions or errors
522	>	* including ClassCastException.
523	>	* @param t1 one task
524	>	* @param t2 the other task
525	>	* @throws NullPointerException if t1 or t2 are null
526	>	* @throws RuntimeException or Error if either task did so.
527		*/
528	<	public final void quietlyJoin() {
529	<	if (status >= 0) {
530	<	ForkJoinWorkerThread w = getWorker();
531	<	if (w == null || !w.unpushTask(this) || !tryQuietlyInvoke())
539	<	awaitDone(w, true);
540	<	}
528	>	public static void invokeAll(ForkJoinTask<?>t1, ForkJoinTask<?> t2) {
529	>	t2.fork();
530	>	t1.invoke();
531	>	t2.join();
532		}
533
534		/**
535	<	* Possibly executes other tasks until this task is ready.
535	>	* Forks the given tasks, returning when <code>isDone</code> holds
536	>	* for all of them. If any task encounters an exception, others
537	>	* may be cancelled.  This method may be invoked only from within
538	>	* ForkJoinTask computations. Attempts to invoke in other contexts
539	>	* result in exceptions or errors including ClassCastException.
540	>	* @param tasks the array of tasks
541	>	* @throws NullPointerException if tasks or any element are null.
542	>	* @throws RuntimeException or Error if any task did so.
543		*/
544	<	public final void quietlyHelpJoin() {
545	<	if (status >= 0) {
546	<	ForkJoinWorkerThread w =
547	<	(ForkJoinWorkerThread)(Thread.currentThread());
548	<	if (!w.unpushTask(this) || !tryQuietlyInvoke())
549	<	w.helpJoinTask(this);
544	>	public static void invokeAll(ForkJoinTask<?>... tasks) {
545	>	Throwable ex = null;
546	>	int last = tasks.length - 1;
547	>	for (int i = last; i >= 0; --i) {
548	>	ForkJoinTask<?> t = tasks[i];
549	>	if (t == null) {
550	>	if (ex == null)
551	>	ex = new NullPointerException();
552	>	}
553	>	else if (i != 0)
554	>	t.fork();
555	>	else {
556	>	t.quietlyInvoke();
557	>	if (ex == null)
558	>	ex = t.getException();
559	>	}
560		}
561	+	for (int i = 1; i <= last; ++i) {
562	+	ForkJoinTask<?> t = tasks[i];
563	+	if (t != null) {
564	+	if (ex != null)
565	+	t.cancel(false);
566	+	else {
567	+	t.quietlyJoin();
568	+	if (ex == null)
569	+	ex = t.getException();
570	+	}
571	+	}
572	+	}
573	+	if (ex != null)
574	+	rethrowException(ex);
575		}
576
577		/**
578	<	* Performs this task and awaits its completion if necessary,
579	<	* without returning its result or throwing an exception. This
580	<	* method may be useful when processing collections of tasks when
581	<	* some have been cancelled or otherwise known to have aborted.
578	>	* Forks all tasks in the collection, returning when
579	>	* <code>isDone</code> holds for all of them. If any task
580	>	* encounters an exception, others may be cancelled.  This method
581	>	* may be invoked only from within ForkJoinTask
582	>	* computations. Attempts to invoke in other contexts resul!t in
583	>	* exceptions or errors including ClassCastException.
584	>	* @param tasks the collection of tasks
585	>	* @throws NullPointerException if tasks or any element are null.
586	>	* @throws RuntimeException or Error if any task did so.
587		*/
588	<	public final void quietlyInvoke() {
589	<	if (status >= 0 && !tryQuietlyInvoke())
590	<	quietlyJoin();
588	>	public static void invokeAll(Collection<? extends ForkJoinTask<?>> tasks) {
589	>	if (!(tasks instanceof List)) {
590	>	invokeAll(tasks.toArray(new ForkJoinTask[tasks.size()]));
591	>	return;
592	>	}
593	>	List<? extends ForkJoinTask<?>> ts =
594	>	(List<? extends ForkJoinTask<?>>)tasks;
595	>	Throwable ex = null;
596	>	int last = ts.size() - 1;
597	>	for (int i = last; i >= 0; --i) {
598	>	ForkJoinTask<?> t = ts.get(i);
599	>	if (t == null) {
600	>	if (ex == null)
601	>	ex = new NullPointerException();
602	>	}
603	>	else if (i != 0)
604	>	t.fork();
605	>	else {
606	>	t.quietlyInvoke();
607	>	if (ex == null)
608	>	ex = t.getException();
609	>	}
610	>	}
611	>	for (int i = 1; i <= last; ++i) {
612	>	ForkJoinTask<?> t = ts.get(i);
613	>	if (t != null) {
614	>	if (ex != null)
615	>	t.cancel(false);
616	>	else {
617	>	t.quietlyJoin();
618	>	if (ex == null)
619	>	ex = t.getException();
620	>	}
621	>	}
622	>	}
623	>	if (ex != null)
624	>	rethrowException(ex);
625		}
626
627		/**
#	Line 584 | Line 645 | public abstract class ForkJoinTask<V> im
645		* Returns true if this task threw an exception or was cancelled
646		* @return true if this task threw an exception or was cancelled
647		*/
648	<	public final boolean completedAbnormally() {
648	>	public final boolean isCompletedAbnormally() {
649		return (status & COMPLETION_MASK) < NORMAL;
650		}
651
#	Line 605 | Line 666 | public abstract class ForkJoinTask<V> im
666
667		/**
668		* Asserts that the results of this task's computation will not be
669	<	* used. If a cancellation occurs before this task is processed,
670	<	* then its <tt>compute</tt> method will not be executed,
671	<	* <tt>isCancelled</tt> will report true, and <tt>join</tt> will
672	<	* result in a CancellationException being thrown. Otherwise, when
669	>	* used. If a cancellation occurs before atempting to execute this
670	>	* task, then execution will be suppressed, <code>isCancelled</code>
671	>	* will report true, and <code>join</code> will result in a
672	>	* <code>CancellationException</code> being thrown. Otherwise, when
673		* cancellation races with completion, there are no guarantees
674	<	* about whether <tt>isCancelled</tt> will report true, whether
675	<	* <tt>join</tt> will return normally or via an exception, or
674	>	* about whether <code>isCancelled</code> will report true, whether
675	>	* <code>join</code> will return normally or via an exception, or
676		* whether these behaviors will remain consistent upon repeated
677		* invocation.
678		*
#	Line 622 | Line 683 | public abstract class ForkJoinTask<V> im
683		* <p> This method is designed to be invoked by <em>other</em>
684		* tasks. To terminate the current task, you can just return or
685		* throw an unchecked exception from its computation method, or
686	<	* invoke <tt>completeExceptionally(someException)</tt>.
686	>	* invoke <code>completeExceptionally</code>.
687		*
688		* @param mayInterruptIfRunning this value is ignored in the
689		* default implementation because tasks are not in general
#	Line 638 | Line 699 | public abstract class ForkJoinTask<V> im
699		/**
700		* Completes this task abnormally, and if not already aborted or
701		* cancelled, causes it to throw the given exception upon
702	<	* <tt>join</tt> and related operations. This method may be used
702	>	* <code>join</code> and related operations. This method may be used
703		* to induce exceptions in asynchronous tasks, or to force
704	<	* completion of tasks that would not otherwise complete.  This
705	<	* method is overridable, but overridden versions must invoke
706	<	* <tt>super</tt> implementation to maintain guarantees.
704	>	* completion of tasks that would not otherwise complete.  Its use
705	>	* in other situations is likely to be wrong.  This method is
706	>	* overridable, but overridden versions must invoke <code>super</code>
707	>	* implementation to maintain guarantees.
708	>	*
709		* @param ex the exception to throw. If this exception is
710		* not a RuntimeException or Error, the actual exception thrown
711		* will be a RuntimeException with cause ex.
#	Line 655 | Line 718 | public abstract class ForkJoinTask<V> im
718
719		/**
720		* Completes this task, and if not already aborted or cancelled,
721	<	* returning a <tt>null</tt> result upon <tt>join</tt> and related
721	>	* returning a <code>null</code> result upon <code>join</code> and related
722		* operations. This method may be used to provide results for
723		* asynchronous tasks, or to provide alternative handling for
724	<	* tasks that would not otherwise complete normally.
724	>	* tasks that would not otherwise complete normally. Its use in
725	>	* other situations is likely to be wrong. This method is
726	>	* overridable, but overridden versions must invoke <code>super</code>
727	>	* implementation to maintain guarantees.
728		*
729		* @param value the result value for this task.
730		*/
#	Line 673 | Line 739 | public abstract class ForkJoinTask<V> im
739		}
740
741		/**
742	+	* Possibly executes other tasks until this task is ready, then
743	+	* returns the result of the computation.  This method may be more
744	+	* efficient than <code>join</code>, but is only applicable when
745	+	* there are no potemtial dependencies between continuation of the
746	+	* current task and that of any other task that might be executed
747	+	* while helping. (This usually holds for pure divide-and-conquer
748	+	* tasks). This method may be invoked only from within
749	+	* ForkJoinTask computations. Attempts to invoke in other contexts
750	+	* resul!t in exceptions or errors including ClassCastException.
751	+	* @return the computed result
752	+	*/
753	+	public final V helpJoin() {
754	+	ForkJoinWorkerThread w = (ForkJoinWorkerThread)(Thread.currentThread());
755	+	if (status < 0 || !w.unpushTask(this) || !tryExec())
756	+	reportException(w.helpJoinTask(this));
757	+	return getRawResult();
758	+	}
759	+
760	+	/**
761	+	* Possibly executes other tasks until this task is ready.  This
762	+	* method may be invoked only from within ForkJoinTask
763	+	* computations. Attempts to invoke in other contexts resul!t in
764	+	* exceptions or errors including ClassCastException.
765	+	*/
766	+	public final void quietlyHelpJoin() {
767	+	if (status >= 0) {
768	+	ForkJoinWorkerThread w =
769	+	(ForkJoinWorkerThread)(Thread.currentThread());
770	+	if (!w.unpushTask(this) || !tryQuietlyInvoke())
771	+	w.helpJoinTask(this);
772	+	}
773	+	}
774	+
775	+	/**
776	+	* Joins this task, without returning its result or throwing an
777	+	* exception. This method may be useful when processing
778	+	* collections of tasks when some have been cancelled or otherwise
779	+	* known to have aborted.
780	+	*/
781	+	public final void quietlyJoin() {
782	+	if (status >= 0) {
783	+	ForkJoinWorkerThread w = getWorker();
784	+	if (w == null || !w.unpushTask(this) || !tryQuietlyInvoke())
785	+	awaitDone(w, true);
786	+	}
787	+	}
788	+
789	+	/**
790	+	* Commences performing this task and awaits its completion if
791	+	* necessary, without returning its result or throwing an
792	+	* exception. This method may be useful when processing
793	+	* collections of tasks when some have been cancelled or otherwise
794	+	* known to have aborted.
795	+	*/
796	+	public final void quietlyInvoke() {
797	+	if (status >= 0 && !tryQuietlyInvoke())
798	+	quietlyJoin();
799	+	}
800	+
801	+	/**
802		* Resets the internal bookkeeping state of this task, allowing a
803	<	* subsequent <tt>fork</tt>. This method allows repeated reuse of
803	>	* subsequent <code>fork</code>. This method allows repeated reuse of
804		* this task, but only if reuse occurs when this task has either
805		* never been forked, or has been forked, then completed and all
806		* outstanding joins of this task have also completed. Effects
#	Line 689 | Line 815 | public abstract class ForkJoinTask<V> im
815		}
816
817		/**
818	<	* Tries to unschedule this task for execution. This method will
819	<	* typically succeed if this task is the next task that would be
820	<	* executed by the current thread, and will typically fail (return
695	<	* false) otherwise. This method may be useful when arranging
696	<	* faster local processing of tasks that could have been, but were
697	<	* not, stolen.
698	<	* @return true if unforked
699	<	*/
700	<	public boolean tryUnfork() {
701	<	return ((ForkJoinWorkerThread)(Thread.currentThread())).unpushTask(this);
702	<	}
703	<
704	<	/**
705	<	* Forks both tasks, returning when <tt>isDone</tt> holds for both
706	<	* of them or an exception is encountered. This method may be
707	<	* invoked only from within other ForkJoinTask
708	<	* computations. Attempts to invoke in other contexts result in
709	<	* exceptions or errors including ClassCastException.
710	<	* @param t1 one task
711	<	* @param t2 the other task
712	<	* @throws NullPointerException if t1 or t2 are null
713	<	* @throws RuntimeException or Error if either task did so.
818	>	* Returns the pool hosting the current task execution, or null
819	>	* if this task is executing outside of any pool.
820	>	* @return the pool, or null if none.
821		*/
822	<	public static void invokeAll(ForkJoinTask<?>t1, ForkJoinTask<?> t2) {
823	<	t2.fork();
824	<	t1.invoke();
825	<	t2.join();
822	>	public static ForkJoinPool getPool() {
823	>	Thread t = Thread.currentThread();
824	>	return ((t instanceof ForkJoinWorkerThread)?
825	>	((ForkJoinWorkerThread)t).pool : null);
826		}
827
828		/**
829	<	* Forks the given tasks, returning when <tt>isDone</tt> holds for
830	<	* all of them. If any task encounters an exception, others may be
831	<	* cancelled.  This method may be invoked only from within other
829	>	* Tries to unschedule this task for execution. This method will
830	>	* typically succeed if this task is the most recently forked task
831	>	* by the current thread, and has not commenced executing in
832	>	* another thread.  This method may be useful when arranging
833	>	* alternative local processing of tasks that could have been, but
834	>	* were not, stolen. This method may be invoked only from within
835		* ForkJoinTask computations. Attempts to invoke in other contexts
836		* result in exceptions or errors including ClassCastException.
837	<	* @param tasks the array of tasks
728	<	* @throws NullPointerException if tasks or any element are null.
729	<	* @throws RuntimeException or Error if any task did so.
730	<	*/
731	<	public static void invokeAll(ForkJoinTask<?>... tasks) {
732	<	Throwable ex = null;
733	<	int last = tasks.length - 1;
734	<	for (int i = last; i >= 0; --i) {
735	<	ForkJoinTask<?> t = tasks[i];
736	<	if (t == null) {
737	<	if (ex == null)
738	<	ex = new NullPointerException();
739	<	}
740	<	else if (i != 0)
741	<	t.fork();
742	<	else {
743	<	t.quietlyInvoke();
744	<	if (ex == null)
745	<	ex = t.getException();
746	<	}
747	<	}
748	<	for (int i = 1; i <= last; ++i) {
749	<	ForkJoinTask<?> t = tasks[i];
750	<	if (t != null) {
751	<	if (ex != null)
752	<	t.cancel(false);
753	<	else {
754	<	t.quietlyJoin();
755	<	if (ex == null)
756	<	ex = t.getException();
757	<	}
758	<	}
759	<	}
760	<	if (ex != null)
761	<	rethrowException(ex);
762	<	}
763	<
764	<	/**
765	<	* Forks all tasks in the collection, returning when
766	<	* <tt>isDone</tt> holds for all of them. If any task encounters
767	<	* an exception, others may be cancelled.  This method may be
768	<	* invoked only from within other ForkJoinTask
769	<	* computations. Attempts to invoke in other contexts result in
770	<	* exceptions or errors including ClassCastException.
771	<	* @param tasks the collection of tasks
772	<	* @throws NullPointerException if tasks or any element are null.
773	<	* @throws RuntimeException or Error if any task did so.
837	>	* @return true if unforked
838		*/
839	<	public static void invokeAll(Collection<? extends ForkJoinTask<?>> tasks) {
840	<	if (!(tasks instanceof List)) {
777	<	invokeAll(tasks.toArray(new ForkJoinTask[tasks.size()]));
778	<	return;
779	<	}
780	<	List<? extends ForkJoinTask<?>> ts =
781	<	(List<? extends ForkJoinTask<?>>)tasks;
782	<	Throwable ex = null;
783	<	int last = ts.size() - 1;
784	<	for (int i = last; i >= 0; --i) {
785	<	ForkJoinTask<?> t = ts.get(i);
786	<	if (t == null) {
787	<	if (ex == null)
788	<	ex = new NullPointerException();
789	<	}
790	<	else if (i != 0)
791	<	t.fork();
792	<	else {
793	<	t.quietlyInvoke();
794	<	if (ex == null)
795	<	ex = t.getException();
796	<	}
797	<	}
798	<	for (int i = 1; i <= last; ++i) {
799	<	ForkJoinTask<?> t = ts.get(i);
800	<	if (t != null) {
801	<	if (ex != null)
802	<	t.cancel(false);
803	<	else {
804	<	t.quietlyJoin();
805	<	if (ex == null)
806	<	ex = t.getException();
807	<	}
808	<	}
809	<	}
810	<	if (ex != null)
811	<	rethrowException(ex);
839	>	public boolean tryUnfork() {
840	>	return ((ForkJoinWorkerThread)(Thread.currentThread())).unpushTask(this);
841		}
842
843		/**
#	Line 823 | Line 852 | public abstract class ForkJoinTask<V> im
852		}
853
854		/**
855	+	* Returns an estimate of the number of tasks that have been
856	+	* forked by the current worker thread but not yet executed. This
857	+	* value may be useful for heuristic decisions about whether to
858	+	* fork other tasks.
859	+	* @return the number of tasks
860	+	*/
861	+	public static int getQueuedTaskCount() {
862	+	return ((ForkJoinWorkerThread)(Thread.currentThread())).
863	+	getQueueSize();
864	+	}
865	+
866	+	/**
867		* Returns a estimate of how many more locally queued tasks are
868		* held by the current worker thread than there are other worker
869	<	* threads that might want to steal them.  This value may be
870	<	* useful for heuristic decisions about whether to fork other
871	<	* tasks. In many usages of ForkJoinTasks, at steady state, each
872	<	* worker should aim to maintain a small constant surplus (for
873	<	* example, 3) of tasks, and to process computations locally if
874	<	* this threshold is exceeded.
869	>	* threads that might steal them.  This value may be useful for
870	>	* heuristic decisions about whether to fork other tasks. In many
871	>	* usages of ForkJoinTasks, at steady state, each worker should
872	>	* aim to maintain a small constant surplus (for example, 3) of
873	>	* tasks, and to process computations locally if this threshold is
874	>	* exceeded.
875		* @return the surplus number of tasks, which may be negative
876		*/
877	<	public static int surplus() {
877	>	public static int getSurplusQueuedTaskCount() {
878		return ((ForkJoinWorkerThread)(Thread.currentThread()))
879		.getEstimatedSurplusTaskCount();
880		}
881
882	<	// Extension kit
882	>	// Extension methods
883
884		/**
885	<	* Returns the result that would be returned by <tt>join</tt>, or
886	<	* null if this task is not known to have been completed.  This
887	<	* method is designed to aid debugging, as well as to support
888	<	* extensions. Its use in any other context is discouraged.
885	>	* Returns the result that would be returned by <code>join</code>,
886	>	* even if this task completed abnormally, or null if this task is
887	>	* not known to have been completed.  This method is designed to
888	>	* aid debugging, as well as to support extensions. Its use in any
889	>	* other context is discouraged.
890		*
891		* @return the result, or null if not completed.
892		*/
#	Line 865 | Line 907 | public abstract class ForkJoinTask<V> im
907		* called otherwise. The return value controls whether this task
908		* is considered to be done normally. It may return false in
909		* asynchronous actions that require explicit invocations of
910	<	* <tt>complete</tt> to become joinable. It may throw exceptions
910	>	* <code>complete</code> to become joinable. It may throw exceptions
911		* to indicate abnormal exit.
912		* @return true if completed normally
913		* @throws Error or RuntimeException if encountered during computation
914		*/
915		protected abstract boolean exec();
916
917	+	/**
918	+	* Returns, but does not unschedule or execute, the task most
919	+	* recently forked by the current thread but not yet executed, if
920	+	* one is available. There is no guarantee that this task will
921	+	* actually be polled or executed next.
922	+	* This method is designed primarily to support extensions,
923	+	* and is unlikely to be useful otherwise.
924	+	*
925	+	* @return the next task, or null if none are available
926	+	*/
927	+	protected static ForkJoinTask<?> peekNextLocalTask() {
928	+	return ((ForkJoinWorkerThread)(Thread.currentThread())).peekTask();
929	+	}
930	+
931	+	/**
932	+	* Unschedules and returns, without executing, the task most
933	+	* recently forked by the current thread but not yet executed.
934	+	* This method is designed primarily to support extensions,
935	+	* and is unlikely to be useful otherwise.
936	+	*
937	+	* @return the next task, or null if none are available
938	+	*/
939	+	protected static ForkJoinTask<?> pollNextLocalTask() {
940	+	return ((ForkJoinWorkerThread)(Thread.currentThread())).popTask();
941	+	}
942	+
943	+	/**
944	+	* Unschedules and returns, without executing, the task most
945	+	* recently forked by the current thread but not yet executed, if
946	+	* one is available, or if not available, a task that was forked
947	+	* by some other thread, if available. Availability may be
948	+	* transient, so a <code>null</code> result does not necessarily
949	+	* imply quiecence of the pool this task is operating in.
950	+	* This method is designed primarily to support extensions,
951	+	* and is unlikely to be useful otherwise.
952	+	*
953	+	* @return a task, or null if none are available
954	+	*/
955	+	protected static ForkJoinTask<?> pollTask() {
956	+	return ((ForkJoinWorkerThread)(Thread.currentThread())).
957	+	getLocalOrStolenTask();
958	+	}
959	+
960		// Serialization support
961
962		private static final long serialVersionUID = -7721805057305804111L;
#	Line 896 | Line 981 | public abstract class ForkJoinTask<V> im
981		private void readObject(java.io.ObjectInputStream s)
982		throws java.io.IOException, ClassNotFoundException {
983		s.defaultReadObject();
984	<	//        status &= ~INTERNAL_SIGNAL_MASK; //  todo: define policy
984	>	status &= ~INTERNAL_SIGNAL_MASK; // clear internal signal counts
985	>	status |= EXTERNAL_SIGNAL; // conservatively set external signal
986		Object ex = s.readObject();
987		if (ex != null)
988		setDoneExceptionally((Throwable)ex);

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines