ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ForkJoinPool.java
Revision: 1.67
Committed: Wed Jun 8 01:12:17 2011 UTC (12 years, 11 months ago) by jsr166
Branch: MAIN
Changes since 1.66: +1 -2 lines
Log Message:
remove unused locals

File Contents

# User Rev Content
1 jsr166 1.1 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3     * Expert Group and released to the public domain, as explained at
4 jsr166 1.58 * http://creativecommons.org/publicdomain/zero/1.0/
5 jsr166 1.1 */
6    
7     package java.util.concurrent;
8    
9     import java.util.ArrayList;
10     import java.util.Arrays;
11     import java.util.Collection;
12     import java.util.Collections;
13     import java.util.List;
14 dl 1.52 import java.util.Random;
15 dl 1.36 import java.util.concurrent.AbstractExecutorService;
16     import java.util.concurrent.Callable;
17     import java.util.concurrent.ExecutorService;
18     import java.util.concurrent.Future;
19     import java.util.concurrent.RejectedExecutionException;
20     import java.util.concurrent.RunnableFuture;
21     import java.util.concurrent.TimeUnit;
22     import java.util.concurrent.atomic.AtomicInteger;
23 jsr166 1.1 import java.util.concurrent.locks.LockSupport;
24     import java.util.concurrent.locks.ReentrantLock;
25 dl 1.52 import java.util.concurrent.locks.Condition;
26 jsr166 1.1
27     /**
28 jsr166 1.4 * An {@link ExecutorService} for running {@link ForkJoinTask}s.
29 jsr166 1.8 * A {@code ForkJoinPool} provides the entry point for submissions
30 dl 1.18 * from non-{@code ForkJoinTask} clients, as well as management and
31 jsr166 1.11 * monitoring operations.
32 jsr166 1.1 *
33 jsr166 1.9 * <p>A {@code ForkJoinPool} differs from other kinds of {@link
34     * ExecutorService} mainly by virtue of employing
35     * <em>work-stealing</em>: all threads in the pool attempt to find and
36     * execute subtasks created by other active tasks (eventually blocking
37     * waiting for work if none exist). This enables efficient processing
38     * when most tasks spawn other subtasks (as do most {@code
39 dl 1.18 * ForkJoinTask}s). When setting <em>asyncMode</em> to true in
40     * constructors, {@code ForkJoinPool}s may also be appropriate for use
41     * with event-style tasks that are never joined.
42 jsr166 1.1 *
43 jsr166 1.9 * <p>A {@code ForkJoinPool} is constructed with a given target
44     * parallelism level; by default, equal to the number of available
45 dl 1.18 * processors. The pool attempts to maintain enough active (or
46     * available) threads by dynamically adding, suspending, or resuming
47     * internal worker threads, even if some tasks are stalled waiting to
48     * join others. However, no such adjustments are guaranteed in the
49     * face of blocked IO or other unmanaged synchronization. The nested
50     * {@link ManagedBlocker} interface enables extension of the kinds of
51     * synchronization accommodated.
52 jsr166 1.1 *
53     * <p>In addition to execution and lifecycle control methods, this
54     * class provides status check methods (for example
55 jsr166 1.4 * {@link #getStealCount}) that are intended to aid in developing,
56 jsr166 1.1 * tuning, and monitoring fork/join applications. Also, method
57 jsr166 1.4 * {@link #toString} returns indications of pool state in a
58 jsr166 1.1 * convenient form for informal monitoring.
59     *
60 dl 1.18 * <p> As is the case with other ExecutorServices, there are three
61 dl 1.19 * main task execution methods summarized in the following
62 dl 1.18 * table. These are designed to be used by clients not already engaged
63     * in fork/join computations in the current pool. The main forms of
64     * these methods accept instances of {@code ForkJoinTask}, but
65     * overloaded forms also allow mixed execution of plain {@code
66     * Runnable}- or {@code Callable}- based activities as well. However,
67     * tasks that are already executing in a pool should normally
68     * <em>NOT</em> use these pool execution methods, but instead use the
69 dl 1.19 * within-computation forms listed in the table.
70 dl 1.18 *
71     * <table BORDER CELLPADDING=3 CELLSPACING=1>
72     * <tr>
73     * <td></td>
74     * <td ALIGN=CENTER> <b>Call from non-fork/join clients</b></td>
75     * <td ALIGN=CENTER> <b>Call from within fork/join computations</b></td>
76     * </tr>
77     * <tr>
78 jsr166 1.25 * <td> <b>Arrange async execution</td>
79 dl 1.18 * <td> {@link #execute(ForkJoinTask)}</td>
80     * <td> {@link ForkJoinTask#fork}</td>
81     * </tr>
82     * <tr>
83     * <td> <b>Await and obtain result</td>
84     * <td> {@link #invoke(ForkJoinTask)}</td>
85     * <td> {@link ForkJoinTask#invoke}</td>
86     * </tr>
87     * <tr>
88     * <td> <b>Arrange exec and obtain Future</td>
89     * <td> {@link #submit(ForkJoinTask)}</td>
90     * <td> {@link ForkJoinTask#fork} (ForkJoinTasks <em>are</em> Futures)</td>
91     * </tr>
92     * </table>
93 dl 1.19 *
94 jsr166 1.9 * <p><b>Sample Usage.</b> Normally a single {@code ForkJoinPool} is
95     * used for all parallel task execution in a program or subsystem.
96     * Otherwise, use would not usually outweigh the construction and
97     * bookkeeping overhead of creating a large set of threads. For
98     * example, a common pool could be used for the {@code SortTasks}
99     * illustrated in {@link RecursiveAction}. Because {@code
100     * ForkJoinPool} uses threads in {@linkplain java.lang.Thread#isDaemon
101     * daemon} mode, there is typically no need to explicitly {@link
102     * #shutdown} such a pool upon program exit.
103     *
104     * <pre>
105     * static final ForkJoinPool mainPool = new ForkJoinPool();
106     * ...
107     * public void sort(long[] array) {
108     * mainPool.invoke(new SortTask(array, 0, array.length));
109     * }
110     * </pre>
111     *
112 jsr166 1.1 * <p><b>Implementation notes</b>: This implementation restricts the
113     * maximum number of running threads to 32767. Attempts to create
114 jsr166 1.11 * pools with greater than the maximum number result in
115 jsr166 1.8 * {@code IllegalArgumentException}.
116 jsr166 1.1 *
117 jsr166 1.11 * <p>This implementation rejects submitted tasks (that is, by throwing
118 dl 1.19 * {@link RejectedExecutionException}) only when the pool is shut down
119 dl 1.20 * or internal resources have been exhausted.
120 jsr166 1.11 *
121 jsr166 1.1 * @since 1.7
122     * @author Doug Lea
123     */
124     public class ForkJoinPool extends AbstractExecutorService {
125    
126     /*
127 dl 1.14 * Implementation Overview
128     *
129     * This class provides the central bookkeeping and control for a
130     * set of worker threads: Submissions from non-FJ threads enter
131     * into a submission queue. Workers take these tasks and typically
132     * split them into subtasks that may be stolen by other workers.
133 dl 1.52 * Preference rules give first priority to processing tasks from
134     * their own queues (LIFO or FIFO, depending on mode), then to
135     * randomized FIFO steals of tasks in other worker queues, and
136     * lastly to new submissions.
137     *
138     * The main throughput advantages of work-stealing stem from
139     * decentralized control -- workers mostly take tasks from
140     * themselves or each other. We cannot negate this in the
141     * implementation of other management responsibilities. The main
142     * tactic for avoiding bottlenecks is packing nearly all
143     * essentially atomic control state into a single 64bit volatile
144     * variable ("ctl"). This variable is read on the order of 10-100
145     * times as often as it is modified (always via CAS). (There is
146     * some additional control state, for example variable "shutdown"
147     * for which we can cope with uncoordinated updates.) This
148     * streamlines synchronization and control at the expense of messy
149     * constructions needed to repack status bits upon updates.
150     * Updates tend not to contend with each other except during
151     * bursts while submitted tasks begin or end. In some cases when
152     * they do contend, threads can instead do something else
153 dl 1.56 * (usually, scan for tasks) until contention subsides.
154 dl 1.52 *
155     * To enable packing, we restrict maximum parallelism to (1<<15)-1
156     * (which is far in excess of normal operating range) to allow
157     * ids, counts, and their negations (used for thresholding) to fit
158     * into 16bit fields.
159     *
160     * Recording Workers. Workers are recorded in the "workers" array
161     * that is created upon pool construction and expanded if (rarely)
162     * necessary. This is an array as opposed to some other data
163     * structure to support index-based random steals by workers.
164     * Updates to the array recording new workers and unrecording
165     * terminated ones are protected from each other by a seqLock
166     * (scanGuard) but the array is otherwise concurrently readable,
167     * and accessed directly by workers. To simplify index-based
168     * operations, the array size is always a power of two, and all
169     * readers must tolerate null slots. To avoid flailing during
170     * start-up, the array is presized to hold twice #parallelism
171     * workers (which is unlikely to need further resizing during
172     * execution). But to avoid dealing with so many null slots,
173     * variable scanGuard includes a mask for the nearest power of two
174     * that contains all current workers. All worker thread creation
175     * is on-demand, triggered by task submissions, replacement of
176     * terminated workers, and/or compensation for blocked
177     * workers. However, all other support code is set up to work with
178     * other policies. To ensure that we do not hold on to worker
179     * references that would prevent GC, ALL accesses to workers are
180     * via indices into the workers array (which is one source of some
181     * of the messy code constructions here). In essence, the workers
182     * array serves as a weak reference mechanism. Thus for example
183     * the wait queue field of ctl stores worker indices, not worker
184     * references. Access to the workers in associated methods (for
185     * example signalWork) must both index-check and null-check the
186     * IDs. All such accesses ignore bad IDs by returning out early
187     * from what they are doing, since this can only be associated
188     * with termination, in which case it is OK to give up.
189     *
190     * All uses of the workers array, as well as queue arrays, check
191     * that the array is non-null (even if previously non-null). This
192     * allows nulling during termination, which is currently not
193     * necessary, but remains an option for resource-revocation-based
194     * shutdown schemes.
195     *
196     * Wait Queuing. Unlike HPC work-stealing frameworks, we cannot
197 dl 1.56 * let workers spin indefinitely scanning for tasks when none can
198     * be found immediately, and we cannot start/resume workers unless
199     * there appear to be tasks available. On the other hand, we must
200     * quickly prod them into action when new tasks are submitted or
201     * generated. We park/unpark workers after placing in an event
202     * wait queue when they cannot find work. This "queue" is actually
203     * a simple Treiber stack, headed by the "id" field of ctl, plus a
204     * 15bit counter value to both wake up waiters (by advancing their
205     * count) and avoid ABA effects. Successors are held in worker
206     * field "nextWait". Queuing deals with several intrinsic races,
207     * mainly that a task-producing thread can miss seeing (and
208     * signalling) another thread that gave up looking for work but
209     * has not yet entered the wait queue. We solve this by requiring
210     * a full sweep of all workers both before (in scan()) and after
211     * (in tryAwaitWork()) a newly waiting worker is added to the wait
212     * queue. During a rescan, the worker might release some other
213     * queued worker rather than itself, which has the same net
214     * effect. Because enqueued workers may actually be rescanning
215     * rather than waiting, we set and clear the "parked" field of
216     * ForkJoinWorkerThread to reduce unnecessary calls to unpark.
217     * (Use of the parked field requires a secondary recheck to avoid
218     * missed signals.)
219 dl 1.52 *
220     * Signalling. We create or wake up workers only when there
221     * appears to be at least one task they might be able to find and
222     * execute. When a submission is added or another worker adds a
223     * task to a queue that previously had two or fewer tasks, they
224     * signal waiting workers (or trigger creation of new ones if
225     * fewer than the given parallelism level -- see signalWork).
226     * These primary signals are buttressed by signals during rescans
227     * as well as those performed when a worker steals a task and
228     * notices that there are more tasks too; together these cover the
229     * signals needed in cases when more than two tasks are pushed
230     * but untaken.
231     *
232     * Trimming workers. To release resources after periods of lack of
233     * use, a worker starting to wait when the pool is quiescent will
234     * time out and terminate if the pool has remained quiescent for
235 dl 1.56 * SHRINK_RATE nanosecs. This will slowly propagate, eventually
236     * terminating all workers after long periods of non-use.
237 dl 1.52 *
238     * Submissions. External submissions are maintained in an
239     * array-based queue that is structured identically to
240 dl 1.56 * ForkJoinWorkerThread queues except for the use of
241     * submissionLock in method addSubmission. Unlike the case for
242     * worker queues, multiple external threads can add new
243     * submissions, so adding requires a lock.
244 dl 1.52 *
245     * Compensation. Beyond work-stealing support and lifecycle
246     * control, the main responsibility of this framework is to take
247     * actions when one worker is waiting to join a task stolen (or
248     * always held by) another. Because we are multiplexing many
249     * tasks on to a pool of workers, we can't just let them block (as
250     * in Thread.join). We also cannot just reassign the joiner's
251     * run-time stack with another and replace it later, which would
252     * be a form of "continuation", that even if possible is not
253     * necessarily a good idea since we sometimes need both an
254     * unblocked task and its continuation to progress. Instead we
255 dl 1.19 * combine two tactics:
256     *
257     * Helping: Arranging for the joiner to execute some task that it
258     * would be running if the steal had not occurred. Method
259 dl 1.52 * ForkJoinWorkerThread.joinTask tracks joining->stealing
260 dl 1.19 * links to try to find such a task.
261     *
262     * Compensating: Unless there are already enough live threads,
263 dl 1.52 * method tryPreBlock() may create or re-activate a spare
264     * thread to compensate for blocked joiners until they
265     * unblock.
266     *
267     * The ManagedBlocker extension API can't use helping so relies
268     * only on compensation in method awaitBlocker.
269 dl 1.19 *
270 dl 1.52 * It is impossible to keep exactly the target parallelism number
271     * of threads running at any given time. Determining the
272 dl 1.24 * existence of conservatively safe helping targets, the
273     * availability of already-created spares, and the apparent need
274     * to create new spares are all racy and require heuristic
275 dl 1.52 * guidance, so we rely on multiple retries of each. Currently,
276     * in keeping with on-demand signalling policy, we compensate only
277     * if blocking would leave less than one active (non-waiting,
278     * non-blocked) worker. Additionally, to avoid some false alarms
279     * due to GC, lagging counters, system activity, etc, compensated
280 dl 1.56 * blocking for joins is only attempted after rechecks stabilize
281     * (retries are interspersed with Thread.yield, for good
282     * citizenship). The variable blockedCount, incremented before
283     * blocking and decremented after, is sometimes needed to
284     * distinguish cases of waiting for work vs blocking on joins or
285     * other managed sync. Both cases are equivalent for most pool
286     * control, so we can update non-atomically. (Additionally,
287     * contention on blockedCount alleviates some contention on ctl).
288 dl 1.52 *
289     * Shutdown and Termination. A call to shutdownNow atomically sets
290     * the ctl stop bit and then (non-atomically) sets each workers
291     * "terminate" status, cancels all unprocessed tasks, and wakes up
292     * all waiting workers. Detecting whether termination should
293     * commence after a non-abrupt shutdown() call requires more work
294     * and bookkeeping. We need consensus about quiesence (i.e., that
295     * there is no more work) which is reflected in active counts so
296     * long as there are no current blockers, as well as possible
297     * re-evaluations during independent changes in blocking or
298     * quiescing workers.
299 dl 1.19 *
300 dl 1.52 * Style notes: There is a lot of representation-level coupling
301 dl 1.14 * among classes ForkJoinPool, ForkJoinWorkerThread, and
302 dl 1.52 * ForkJoinTask. Most fields of ForkJoinWorkerThread maintain
303     * data structures managed by ForkJoinPool, so are directly
304     * accessed. Conversely we allow access to "workers" array by
305 dl 1.14 * workers, and direct access to ForkJoinTask.status by both
306     * ForkJoinPool and ForkJoinWorkerThread. There is little point
307     * trying to reduce this, since any associated future changes in
308     * representations will need to be accompanied by algorithmic
309 dl 1.52 * changes anyway. All together, these low-level implementation
310     * choices produce as much as a factor of 4 performance
311     * improvement compared to naive implementations, and enable the
312     * processing of billions of tasks per second, at the expense of
313     * some ugliness.
314     *
315     * Methods signalWork() and scan() are the main bottlenecks so are
316     * especially heavily micro-optimized/mangled. There are lots of
317     * inline assignments (of form "while ((local = field) != 0)")
318     * which are usually the simplest way to ensure the required read
319     * orderings (which are sometimes critical). This leads to a
320     * "C"-like style of listing declarations of these locals at the
321     * heads of methods or blocks. There are several occurrences of
322     * the unusual "do {} while (!cas...)" which is the simplest way
323     * to force an update of a CAS'ed variable. There are also other
324     * coding oddities that help some methods perform reasonably even
325     * when interpreted (not compiled).
326     *
327     * The order of declarations in this file is: (1) declarations of
328     * statics (2) fields (along with constants used when unpacking
329     * some of them), listed in an order that tends to reduce
330     * contention among them a bit under most JVMs. (3) internal
331     * control methods (4) callbacks and other support for
332     * ForkJoinTask and ForkJoinWorkerThread classes, (5) exported
333     * methods (plus a few little helpers). (6) static block
334     * initializing all statics in a minimally dependent order.
335 jsr166 1.1 */
336    
337     /**
338 jsr166 1.8 * Factory for creating new {@link ForkJoinWorkerThread}s.
339     * A {@code ForkJoinWorkerThreadFactory} must be defined and used
340     * for {@code ForkJoinWorkerThread} subclasses that extend base
341     * functionality or initialize threads with different contexts.
342 jsr166 1.1 */
343     public static interface ForkJoinWorkerThreadFactory {
344     /**
345     * Returns a new worker thread operating in the given pool.
346     *
347     * @param pool the pool this thread works in
348 jsr166 1.11 * @throws NullPointerException if the pool is null
349 jsr166 1.1 */
350     public ForkJoinWorkerThread newThread(ForkJoinPool pool);
351     }
352    
353     /**
354     * Default ForkJoinWorkerThreadFactory implementation; creates a
355     * new ForkJoinWorkerThread.
356     */
357 dl 1.18 static class DefaultForkJoinWorkerThreadFactory
358 jsr166 1.1 implements ForkJoinWorkerThreadFactory {
359     public ForkJoinWorkerThread newThread(ForkJoinPool pool) {
360 dl 1.14 return new ForkJoinWorkerThread(pool);
361 jsr166 1.1 }
362     }
363    
364     /**
365     * Creates a new ForkJoinWorkerThread. This factory is used unless
366     * overridden in ForkJoinPool constructors.
367     */
368     public static final ForkJoinWorkerThreadFactory
369 dl 1.52 defaultForkJoinWorkerThreadFactory;
370 jsr166 1.1
371     /**
372     * Permission required for callers of methods that may start or
373     * kill threads.
374     */
375 dl 1.52 private static final RuntimePermission modifyThreadPermission;
376 jsr166 1.1
377     /**
378     * If there is a security manager, makes sure caller has
379     * permission to modify threads.
380     */
381     private static void checkPermission() {
382     SecurityManager security = System.getSecurityManager();
383     if (security != null)
384     security.checkPermission(modifyThreadPermission);
385     }
386    
387     /**
388     * Generator for assigning sequence numbers as pool names.
389     */
390 dl 1.52 private static final AtomicInteger poolNumberGenerator;
391 jsr166 1.1
392     /**
393 dl 1.52 * Generator for initial random seeds for worker victim
394     * selection. This is used only to create initial seeds. Random
395     * steals use a cheaper xorshift generator per steal attempt. We
396     * don't expect much contention on seedGenerator, so just use a
397     * plain Random.
398 dl 1.24 */
399 dl 1.52 static final Random workerSeedGenerator;
400 dl 1.24
401     /**
402 dl 1.52 * Array holding all worker threads in the pool. Initialized upon
403     * construction. Array size must be a power of two. Updates and
404     * replacements are protected by scanGuard, but the array is
405     * always kept in a consistent enough state to be randomly
406     * accessed without locking by workers performing work-stealing,
407     * as well as other traversal-based methods in this class, so long
408     * as reads memory-acquire by first reading ctl. All readers must
409     * tolerate that some array slots may be null.
410 dl 1.22 */
411 dl 1.52 ForkJoinWorkerThread[] workers;
412 dl 1.22
413     /**
414 dl 1.52 * Initial size for submission queue array. Must be a power of
415     * two. In many applications, these always stay small so we use a
416     * small initial cap.
417 dl 1.14 */
418 dl 1.52 private static final int INITIAL_QUEUE_CAPACITY = 8;
419 dl 1.14
420     /**
421 dl 1.52 * Maximum size for submission queue array. Must be a power of two
422     * less than or equal to 1 << (31 - width of array entry) to
423     * ensure lack of index wraparound, but is capped at a lower
424     * value to help users trap runaway computations.
425 jsr166 1.1 */
426 dl 1.52 private static final int MAXIMUM_QUEUE_CAPACITY = 1 << 24; // 16M
427 jsr166 1.1
428     /**
429 dl 1.52 * Array serving as submission queue. Initialized upon construction.
430 jsr166 1.1 */
431 dl 1.52 private ForkJoinTask<?>[] submissionQueue;
432 jsr166 1.1
433     /**
434 dl 1.52 * Lock protecting submissions array for addSubmission
435 jsr166 1.1 */
436 dl 1.52 private final ReentrantLock submissionLock;
437 jsr166 1.1
438     /**
439 dl 1.52 * Condition for awaitTermination, using submissionLock for
440     * convenience.
441 jsr166 1.1 */
442 dl 1.52 private final Condition termination;
443 jsr166 1.1
444     /**
445     * Creation factory for worker threads.
446     */
447     private final ForkJoinWorkerThreadFactory factory;
448    
449     /**
450 dl 1.52 * The uncaught exception handler used when any worker abruptly
451     * terminates.
452 jsr166 1.1 */
453 dl 1.52 final Thread.UncaughtExceptionHandler ueh;
454 jsr166 1.1
455     /**
456 dl 1.52 * Prefix for assigning names to worker threads
457 jsr166 1.1 */
458 dl 1.52 private final String workerNamePrefix;
459 dl 1.14
460 dl 1.52 /**
461     * Sum of per-thread steal counts, updated only when threads are
462     * idle or terminating.
463     */
464     private volatile long stealCount;
465 jsr166 1.1
466     /**
467 dl 1.52 * Main pool control -- a long packed with:
468     * AC: Number of active running workers minus target parallelism (16 bits)
469     * TC: Number of total workers minus target parallelism (16bits)
470     * ST: true if pool is terminating (1 bit)
471     * EC: the wait count of top waiting thread (15 bits)
472     * ID: ~poolIndex of top of Treiber stack of waiting threads (16 bits)
473     *
474     * When convenient, we can extract the upper 32 bits of counts and
475     * the lower 32 bits of queue state, u = (int)(ctl >>> 32) and e =
476     * (int)ctl. The ec field is never accessed alone, but always
477     * together with id and st. The offsets of counts by the target
478     * parallelism and the positionings of fields makes it possible to
479     * perform the most common checks via sign tests of fields: When
480     * ac is negative, there are not enough active workers, when tc is
481     * negative, there are not enough total workers, when id is
482     * negative, there is at least one waiting worker, and when e is
483     * negative, the pool is terminating. To deal with these possibly
484     * negative fields, we use casts in and out of "short" and/or
485 dl 1.55 * signed shifts to maintain signedness.
486 dl 1.52 */
487     volatile long ctl;
488    
489     // bit positions/shifts for fields
490     private static final int AC_SHIFT = 48;
491     private static final int TC_SHIFT = 32;
492     private static final int ST_SHIFT = 31;
493     private static final int EC_SHIFT = 16;
494    
495     // bounds
496     private static final int MAX_ID = 0x7fff; // max poolIndex
497     private static final int SMASK = 0xffff; // mask short bits
498     private static final int SHORT_SIGN = 1 << 15;
499     private static final int INT_SIGN = 1 << 31;
500    
501     // masks
502     private static final long STOP_BIT = 0x0001L << ST_SHIFT;
503     private static final long AC_MASK = ((long)SMASK) << AC_SHIFT;
504     private static final long TC_MASK = ((long)SMASK) << TC_SHIFT;
505    
506     // units for incrementing and decrementing
507     private static final long TC_UNIT = 1L << TC_SHIFT;
508     private static final long AC_UNIT = 1L << AC_SHIFT;
509    
510     // masks and units for dealing with u = (int)(ctl >>> 32)
511     private static final int UAC_SHIFT = AC_SHIFT - 32;
512     private static final int UTC_SHIFT = TC_SHIFT - 32;
513     private static final int UAC_MASK = SMASK << UAC_SHIFT;
514     private static final int UTC_MASK = SMASK << UTC_SHIFT;
515     private static final int UAC_UNIT = 1 << UAC_SHIFT;
516     private static final int UTC_UNIT = 1 << UTC_SHIFT;
517    
518     // masks and units for dealing with e = (int)ctl
519     private static final int E_MASK = 0x7fffffff; // no STOP_BIT
520     private static final int EC_UNIT = 1 << EC_SHIFT;
521 dl 1.14
522     /**
523 dl 1.52 * The target parallelism level.
524 dl 1.19 */
525 dl 1.52 final int parallelism;
526 dl 1.19
527     /**
528 dl 1.52 * Index (mod submission queue length) of next element to take
529 dl 1.56 * from submission queue. Usage is identical to that for
530     * per-worker queues -- see ForkJoinWorkerThread internal
531     * documentation.
532 dl 1.14 */
533 dl 1.52 volatile int queueBase;
534 jsr166 1.1
535     /**
536 dl 1.52 * Index (mod submission queue length) of next element to add
537 dl 1.56 * in submission queue. Usage is identical to that for
538     * per-worker queues -- see ForkJoinWorkerThread internal
539     * documentation.
540 dl 1.14 */
541 dl 1.52 int queueTop;
542 dl 1.14
543 jsr166 1.1 /**
544 dl 1.52 * True when shutdown() has been called.
545 jsr166 1.1 */
546 dl 1.52 volatile boolean shutdown;
547 jsr166 1.1
548     /**
549 dl 1.14 * True if use local fifo, not default lifo, for local polling
550 dl 1.18 * Read by, and replicated by ForkJoinWorkerThreads
551 jsr166 1.1 */
552 dl 1.18 final boolean locallyFifo;
553 jsr166 1.1
554     /**
555 dl 1.52 * The number of threads in ForkJoinWorkerThreads.helpQuiescePool.
556     * When non-zero, suppresses automatic shutdown when active
557     * counts become zero.
558 jsr166 1.1 */
559 dl 1.52 volatile int quiescerCount;
560 jsr166 1.1
561     /**
562 dl 1.52 * The number of threads blocked in join.
563 jsr166 1.1 */
564 dl 1.52 volatile int blockedCount;
565 jsr166 1.1
566 dl 1.52 /**
567     * Counter for worker Thread names (unrelated to their poolIndex)
568     */
569     private volatile int nextWorkerNumber;
570 jsr166 1.1
571     /**
572 dl 1.52 * The index for the next created worker. Accessed under scanGuard.
573 jsr166 1.1 */
574 dl 1.52 private int nextWorkerIndex;
575 dl 1.19
576 jsr166 1.1 /**
577 dl 1.56 * SeqLock and index masking for updates to workers array. Locked
578     * when SG_UNIT is set. Unlocking clears bit by adding
579 dl 1.52 * SG_UNIT. Staleness of read-only operations can be checked by
580     * comparing scanGuard to value before the reads. The low 16 bits
581     * (i.e, anding with SMASK) hold (the smallest power of two
582     * covering all worker indices, minus one, and is used to avoid
583     * dealing with large numbers of null slots when the workers array
584     * is overallocated.
585 dl 1.45 */
586 dl 1.52 volatile int scanGuard;
587    
588     private static final int SG_UNIT = 1 << 16;
589 dl 1.45
590     /**
591 dl 1.52 * The wakeup interval (in nanoseconds) for a worker waiting for a
592     * task when the pool is quiescent to instead try to shrink the
593     * number of workers. The exact value does not matter too
594     * much. It must be short enough to release resources during
595     * sustained periods of idleness, but not so short that threads
596     * are continually re-created.
597 dl 1.17 */
598 dl 1.52 private static final long SHRINK_RATE =
599     4L * 1000L * 1000L * 1000L; // 4 seconds
600 dl 1.17
601     /**
602 dl 1.52 * Top-level loop for worker threads: On each step: if the
603     * previous step swept through all queues and found no tasks, or
604     * there are excess threads, then possibly blocks. Otherwise,
605     * scans for and, if found, executes a task. Returns when pool
606     * and/or worker terminate.
607 dl 1.19 *
608 dl 1.52 * @param w the worker
609 dl 1.19 */
610 dl 1.52 final void work(ForkJoinWorkerThread w) {
611     boolean swept = false; // true on empty scans
612     long c;
613     while (!w.terminate && (int)(c = ctl) >= 0) {
614     int a; // active count
615     if (!swept && (a = (int)(c >> AC_SHIFT)) <= 0)
616     swept = scan(w, a);
617     else if (tryAwaitWork(w, c))
618     swept = false;
619 dl 1.19 }
620     }
621    
622 dl 1.52 // Signalling
623    
624 dl 1.19 /**
625 dl 1.52 * Wakes up or creates a worker.
626 dl 1.14 */
627 dl 1.52 final void signalWork() {
628     /*
629     * The while condition is true if: (there is are too few total
630     * workers OR there is at least one waiter) AND (there are too
631     * few active workers OR the pool is terminating). The value
632     * of e distinguishes the remaining cases: zero (no waiters)
633     * for create, negative if terminating (in which case do
634     * nothing), else release a waiter. The secondary checks for
635     * release (non-null array etc) can fail if the pool begins
636     * terminating after the test, and don't impose any added cost
637     * because JVMs must perform null and bounds checks anyway.
638     */
639     long c; int e, u;
640     while ((((e = (int)(c = ctl)) | (u = (int)(c >>> 32))) &
641     (INT_SIGN|SHORT_SIGN)) == (INT_SIGN|SHORT_SIGN) && e >= 0) {
642     if (e > 0) { // release a waiting worker
643     int i; ForkJoinWorkerThread w; ForkJoinWorkerThread[] ws;
644     if ((ws = workers) == null ||
645     (i = ~e & SMASK) >= ws.length ||
646     (w = ws[i]) == null)
647     break;
648     long nc = (((long)(w.nextWait & E_MASK)) |
649     ((long)(u + UAC_UNIT) << 32));
650     if (w.eventCount == e &&
651     UNSAFE.compareAndSwapLong(this, ctlOffset, c, nc)) {
652     w.eventCount = (e + EC_UNIT) & E_MASK;
653     if (w.parked)
654     UNSAFE.unpark(w);
655     break;
656     }
657     }
658     else if (UNSAFE.compareAndSwapLong
659     (this, ctlOffset, c,
660     (long)(((u + UTC_UNIT) & UTC_MASK) |
661     ((u + UAC_UNIT) & UAC_MASK)) << 32)) {
662     addWorker();
663     break;
664     }
665     }
666 dl 1.14 }
667    
668     /**
669 dl 1.52 * Variant of signalWork to help release waiters on rescans.
670     * Tries once to release a waiter if active count < 0.
671     *
672     * @return false if failed due to contention, else true
673 dl 1.14 */
674 dl 1.52 private boolean tryReleaseWaiter() {
675     long c; int e, i; ForkJoinWorkerThread w; ForkJoinWorkerThread[] ws;
676     if ((e = (int)(c = ctl)) > 0 &&
677     (int)(c >> AC_SHIFT) < 0 &&
678     (ws = workers) != null &&
679     (i = ~e & SMASK) < ws.length &&
680     (w = ws[i]) != null) {
681     long nc = ((long)(w.nextWait & E_MASK) |
682     ((c + AC_UNIT) & (AC_MASK|TC_MASK)));
683     if (w.eventCount != e ||
684     !UNSAFE.compareAndSwapLong(this, ctlOffset, c, nc))
685 dl 1.14 return false;
686 dl 1.52 w.eventCount = (e + EC_UNIT) & E_MASK;
687     if (w.parked)
688     UNSAFE.unpark(w);
689 dl 1.14 }
690 dl 1.52 return true;
691 dl 1.14 }
692    
693 dl 1.52 // Scanning for tasks
694 dl 1.14
695     /**
696 dl 1.52 * Scans for and, if found, executes one task. Scans start at a
697     * random index of workers array, and randomly select the first
698     * (2*#workers)-1 probes, and then, if all empty, resort to 2
699     * circular sweeps, which is necessary to check quiescence. and
700     * taking a submission only if no stealable tasks were found. The
701     * steal code inside the loop is a specialized form of
702     * ForkJoinWorkerThread.deqTask, followed bookkeeping to support
703     * helpJoinTask and signal propagation. The code for submission
704     * queues is almost identical. On each steal, the worker completes
705     * not only the task, but also all local tasks that this task may
706     * have generated. On detecting staleness or contention when
707     * trying to take a task, this method returns without finishing
708     * sweep, which allows global state rechecks before retry.
709     *
710     * @param w the worker
711     * @param a the number of active workers
712     * @return true if swept all queues without finding a task
713 dl 1.14 */
714 dl 1.52 private boolean scan(ForkJoinWorkerThread w, int a) {
715     int g = scanGuard; // mask 0 avoids useless scans if only one active
716 dl 1.57 int m = (parallelism == 1 - a && blockedCount == 0) ? 0 : g & SMASK;
717 dl 1.52 ForkJoinWorkerThread[] ws = workers;
718     if (ws == null || ws.length <= m) // staleness check
719     return false;
720     for (int r = w.seed, k = r, j = -(m + m); j <= m + m; ++j) {
721     ForkJoinTask<?> t; ForkJoinTask<?>[] q; int b, i;
722     ForkJoinWorkerThread v = ws[k & m];
723     if (v != null && (b = v.queueBase) != v.queueTop &&
724     (q = v.queue) != null && (i = (q.length - 1) & b) >= 0) {
725     long u = (i << ASHIFT) + ABASE;
726     if ((t = q[i]) != null && v.queueBase == b &&
727     UNSAFE.compareAndSwapObject(q, u, t, null)) {
728     int d = (v.queueBase = b + 1) - v.queueTop;
729     v.stealHint = w.poolIndex;
730     if (d != 0)
731     signalWork(); // propagate if nonempty
732     w.execTask(t);
733     }
734     r ^= r << 13; r ^= r >>> 17; w.seed = r ^ (r << 5);
735     return false; // store next seed
736     }
737     else if (j < 0) { // xorshift
738     r ^= r << 13; r ^= r >>> 17; k = r ^= r << 5;
739     }
740     else
741     ++k;
742     }
743     if (scanGuard != g) // staleness check
744     return false;
745     else { // try to take submission
746     ForkJoinTask<?> t; ForkJoinTask<?>[] q; int b, i;
747     if ((b = queueBase) != queueTop &&
748     (q = submissionQueue) != null &&
749     (i = (q.length - 1) & b) >= 0) {
750     long u = (i << ASHIFT) + ABASE;
751     if ((t = q[i]) != null && queueBase == b &&
752     UNSAFE.compareAndSwapObject(q, u, t, null)) {
753     queueBase = b + 1;
754     w.execTask(t);
755     }
756     return false;
757     }
758     return true; // all queues empty
759 dl 1.14 }
760     }
761    
762     /**
763 dl 1.54 * Tries to enqueue worker w in wait queue and await change in
764 dl 1.61 * worker's eventCount. If the pool is quiescent and there is
765     * more than one worker, possibly terminates worker upon exit.
766     * Otherwise, before blocking, rescans queues to avoid missed
767     * signals. Upon finding work, releases at least one worker
768     * (which may be the current worker). Rescans restart upon
769     * detected staleness or failure to release due to
770     * contention. Note the unusual conventions about Thread.interrupt
771     * here and elsewhere: Because interrupts are used solely to alert
772     * threads to check termination, which is checked here anyway, we
773     * clear status (using Thread.interrupted) before any call to
774     * park, so that park does not immediately return due to status
775     * being set via some other unrelated call to interrupt in user
776     * code.
777 dl 1.52 *
778     * @param w the calling worker
779     * @param c the ctl value on entry
780     * @return true if waited or another thread was released upon enq
781 dl 1.14 */
782 dl 1.52 private boolean tryAwaitWork(ForkJoinWorkerThread w, long c) {
783     int v = w.eventCount;
784 dl 1.54 w.nextWait = (int)c; // w's successor record
785 dl 1.52 long nc = (long)(v & E_MASK) | ((c - AC_UNIT) & (AC_MASK|TC_MASK));
786     if (ctl != c || !UNSAFE.compareAndSwapLong(this, ctlOffset, c, nc)) {
787 dl 1.54 long d = ctl; // return true if lost to a deq, to force scan
788 dl 1.52 return (int)d != (int)c && ((d - c) & AC_MASK) >= 0L;
789     }
790 dl 1.54 for (int sc = w.stealCount; sc != 0;) { // accumulate stealCount
791     long s = stealCount;
792     if (UNSAFE.compareAndSwapLong(this, stealCountOffset, s, s + sc))
793     sc = w.stealCount = 0;
794     else if (w.eventCount != v)
795     return true; // update next time
796     }
797 dl 1.62 if ((!shutdown || !tryTerminate(false)) &&
798     (int)c != 0 && parallelism + (int)(nc >> AC_SHIFT) == 0 &&
799 dl 1.53 blockedCount == 0 && quiescerCount == 0)
800 dl 1.54 idleAwaitWork(w, nc, c, v); // quiescent
801     for (boolean rescanned = false;;) {
802 dl 1.52 if (w.eventCount != v)
803     return true;
804 dl 1.54 if (!rescanned) {
805 dl 1.52 int g = scanGuard, m = g & SMASK;
806     ForkJoinWorkerThread[] ws = workers;
807     if (ws != null && m < ws.length) {
808     rescanned = true;
809     for (int i = 0; i <= m; ++i) {
810     ForkJoinWorkerThread u = ws[i];
811     if (u != null) {
812     if (u.queueBase != u.queueTop &&
813     !tryReleaseWaiter())
814     rescanned = false; // contended
815     if (w.eventCount != v)
816     return true;
817     }
818     }
819     }
820     if (scanGuard != g || // stale
821     (queueBase != queueTop && !tryReleaseWaiter()))
822     rescanned = false;
823     if (!rescanned)
824     Thread.yield(); // reduce contention
825     else
826     Thread.interrupted(); // clear before park
827     }
828     else {
829     w.parked = true; // must recheck
830     if (w.eventCount != v) {
831     w.parked = false;
832     return true;
833     }
834     LockSupport.park(this);
835     rescanned = w.parked = false;
836     }
837 dl 1.14 }
838     }
839    
840     /**
841 dl 1.54 * If inactivating worker w has caused pool to become
842     * quiescent, check for pool termination, and wait for event
843     * for up to SHRINK_RATE nanosecs (rescans are unnecessary in
844     * this case because quiescence reflects consensus about lack
845     * of work). On timeout, if ctl has not changed, terminate the
846     * worker. Upon its termination (see deregisterWorker), it may
847     * wake up another worker to possibly repeat this process.
848 dl 1.52 *
849     * @param w the calling worker
850 dl 1.54 * @param currentCtl the ctl value after enqueuing w
851     * @param prevCtl the ctl value if w terminated
852     * @param v the eventCount w awaits change
853     */
854     private void idleAwaitWork(ForkJoinWorkerThread w, long currentCtl,
855     long prevCtl, int v) {
856     if (w.eventCount == v) {
857     if (shutdown)
858     tryTerminate(false);
859     ForkJoinTask.helpExpungeStaleExceptions(); // help clean weak refs
860     while (ctl == currentCtl) {
861     long startTime = System.nanoTime();
862 dl 1.52 w.parked = true;
863 dl 1.54 if (w.eventCount == v) // must recheck
864 dl 1.52 LockSupport.parkNanos(this, SHRINK_RATE);
865     w.parked = false;
866 dl 1.54 if (w.eventCount != v)
867     break;
868 jsr166 1.63 else if (System.nanoTime() - startTime <
869 dl 1.60 SHRINK_RATE - (SHRINK_RATE / 10)) // timing slop
870 dl 1.54 Thread.interrupted(); // spurious wakeup
871     else if (UNSAFE.compareAndSwapLong(this, ctlOffset,
872     currentCtl, prevCtl)) {
873     w.terminate = true; // restore previous
874     w.eventCount = ((int)currentCtl + EC_UNIT) & E_MASK;
875     break;
876 dl 1.52 }
877     }
878     }
879 dl 1.14 }
880    
881 dl 1.52 // Submissions
882 dl 1.14
883     /**
884 dl 1.52 * Enqueues the given task in the submissionQueue. Same idea as
885     * ForkJoinWorkerThread.pushTask except for use of submissionLock.
886     *
887     * @param t the task
888 dl 1.14 */
889 dl 1.52 private void addSubmission(ForkJoinTask<?> t) {
890     final ReentrantLock lock = this.submissionLock;
891     lock.lock();
892     try {
893     ForkJoinTask<?>[] q; int s, m;
894     if ((q = submissionQueue) != null) { // ignore if queue removed
895     long u = (((s = queueTop) & (m = q.length-1)) << ASHIFT)+ABASE;
896     UNSAFE.putOrderedObject(q, u, t);
897     queueTop = s + 1;
898     if (s - queueBase == m)
899     growSubmissionQueue();
900 dl 1.24 }
901 dl 1.52 } finally {
902     lock.unlock();
903 dl 1.14 }
904 dl 1.52 signalWork();
905 dl 1.14 }
906    
907 dl 1.52 // (pollSubmission is defined below with exported methods)
908    
909 dl 1.14 /**
910 dl 1.52 * Creates or doubles submissionQueue array.
911 dl 1.56 * Basically identical to ForkJoinWorkerThread version.
912 dl 1.18 */
913 dl 1.52 private void growSubmissionQueue() {
914     ForkJoinTask<?>[] oldQ = submissionQueue;
915     int size = oldQ != null ? oldQ.length << 1 : INITIAL_QUEUE_CAPACITY;
916     if (size > MAXIMUM_QUEUE_CAPACITY)
917     throw new RejectedExecutionException("Queue capacity exceeded");
918     if (size < INITIAL_QUEUE_CAPACITY)
919     size = INITIAL_QUEUE_CAPACITY;
920     ForkJoinTask<?>[] q = submissionQueue = new ForkJoinTask<?>[size];
921     int mask = size - 1;
922     int top = queueTop;
923     int oldMask;
924     if (oldQ != null && (oldMask = oldQ.length - 1) >= 0) {
925     for (int b = queueBase; b != top; ++b) {
926     long u = ((b & oldMask) << ASHIFT) + ABASE;
927     Object x = UNSAFE.getObjectVolatile(oldQ, u);
928     if (x != null && UNSAFE.compareAndSwapObject(oldQ, u, x, null))
929     UNSAFE.putObjectVolatile
930     (q, ((b & mask) << ASHIFT) + ABASE, x);
931 dl 1.22 }
932     }
933     }
934    
935 dl 1.52 // Blocking support
936    
937 dl 1.22 /**
938 dl 1.52 * Tries to increment blockedCount, decrement active count
939     * (sometimes implicitly) and possibly release or create a
940     * compensating worker in preparation for blocking. Fails
941     * on contention or termination.
942     *
943     * @return true if the caller can block, else should recheck and retry
944     */
945     private boolean tryPreBlock() {
946     int b = blockedCount;
947     if (UNSAFE.compareAndSwapInt(this, blockedCountOffset, b, b + 1)) {
948     int pc = parallelism;
949     do {
950     ForkJoinWorkerThread[] ws; ForkJoinWorkerThread w;
951 jsr166 1.67 int e, ac, tc, i;
952 dl 1.52 long c = ctl;
953     int u = (int)(c >>> 32);
954     if ((e = (int)c) < 0) {
955     // skip -- terminating
956     }
957     else if ((ac = (u >> UAC_SHIFT)) <= 0 && e != 0 &&
958     (ws = workers) != null &&
959     (i = ~e & SMASK) < ws.length &&
960     (w = ws[i]) != null) {
961     long nc = ((long)(w.nextWait & E_MASK) |
962     (c & (AC_MASK|TC_MASK)));
963     if (w.eventCount == e &&
964     UNSAFE.compareAndSwapLong(this, ctlOffset, c, nc)) {
965     w.eventCount = (e + EC_UNIT) & E_MASK;
966     if (w.parked)
967     UNSAFE.unpark(w);
968     return true; // release an idle worker
969     }
970     }
971     else if ((tc = (short)(u >>> UTC_SHIFT)) >= 0 && ac + pc > 1) {
972     long nc = ((c - AC_UNIT) & AC_MASK) | (c & ~AC_MASK);
973     if (UNSAFE.compareAndSwapLong(this, ctlOffset, c, nc))
974     return true; // no compensation needed
975     }
976     else if (tc + pc < MAX_ID) {
977     long nc = ((c + TC_UNIT) & TC_MASK) | (c & ~TC_MASK);
978     if (UNSAFE.compareAndSwapLong(this, ctlOffset, c, nc)) {
979     addWorker();
980     return true; // create a replacement
981     }
982 dl 1.19 }
983 dl 1.52 // try to back out on any failure and let caller retry
984     } while (!UNSAFE.compareAndSwapInt(this, blockedCountOffset,
985     b = blockedCount, b - 1));
986 dl 1.14 }
987 dl 1.52 return false;
988 dl 1.22 }
989    
990 dl 1.52 /**
991 jsr166 1.66 * Decrements blockedCount and increments active count.
992 dl 1.52 */
993     private void postBlock() {
994     long c;
995     do {} while (!UNSAFE.compareAndSwapLong(this, ctlOffset, // no mask
996     c = ctl, c + AC_UNIT));
997     int b;
998 jsr166 1.63 do {} while (!UNSAFE.compareAndSwapInt(this, blockedCountOffset,
999     b = blockedCount, b - 1));
1000 dl 1.52 }
1001 dl 1.19
1002     /**
1003 dl 1.52 * Possibly blocks waiting for the given task to complete, or
1004     * cancels the task if terminating. Fails to wait if contended.
1005     *
1006     * @param joinMe the task
1007 dl 1.19 */
1008 dl 1.52 final void tryAwaitJoin(ForkJoinTask<?> joinMe) {
1009     Thread.interrupted(); // clear interrupts before checking termination
1010     if (joinMe.status >= 0) {
1011     if (tryPreBlock()) {
1012     joinMe.tryAwaitDone(0L);
1013     postBlock();
1014     }
1015 dl 1.56 else if ((ctl & STOP_BIT) != 0L)
1016 dl 1.52 joinMe.cancelIgnoringExceptions();
1017     }
1018 dl 1.14 }
1019    
1020     /**
1021 dl 1.52 * Possibly blocks the given worker waiting for joinMe to
1022 jsr166 1.66 * complete or timeout.
1023 dl 1.52 *
1024     * @param joinMe the task
1025     * @param millis the wait time for underlying Object.wait
1026 dl 1.14 */
1027 dl 1.52 final void timedAwaitJoin(ForkJoinTask<?> joinMe, long nanos) {
1028     while (joinMe.status >= 0) {
1029     Thread.interrupted();
1030     if ((ctl & STOP_BIT) != 0L) {
1031     joinMe.cancelIgnoringExceptions();
1032     break;
1033     }
1034     if (tryPreBlock()) {
1035     long last = System.nanoTime();
1036     while (joinMe.status >= 0) {
1037     long millis = TimeUnit.NANOSECONDS.toMillis(nanos);
1038     if (millis <= 0)
1039     break;
1040     joinMe.tryAwaitDone(millis);
1041     if (joinMe.status < 0)
1042     break;
1043     if ((ctl & STOP_BIT) != 0L) {
1044     joinMe.cancelIgnoringExceptions();
1045     break;
1046     }
1047     long now = System.nanoTime();
1048     nanos -= now - last;
1049     last = now;
1050     }
1051     postBlock();
1052     break;
1053     }
1054 dl 1.22 }
1055     }
1056    
1057     /**
1058 jsr166 1.66 * If necessary, compensates for blocker, and blocks.
1059 dl 1.22 */
1060 dl 1.52 private void awaitBlocker(ManagedBlocker blocker)
1061     throws InterruptedException {
1062     while (!blocker.isReleasable()) {
1063     if (tryPreBlock()) {
1064 dl 1.24 try {
1065 dl 1.52 do {} while (!blocker.isReleasable() && !blocker.block());
1066     } finally {
1067     postBlock();
1068 dl 1.24 }
1069 dl 1.52 break;
1070 dl 1.22 }
1071     }
1072     }
1073    
1074 dl 1.52 // Creating, registering and deregistring workers
1075    
1076 dl 1.22 /**
1077 dl 1.52 * Tries to create and start a worker; minimally rolls back counts
1078     * on failure.
1079 dl 1.22 */
1080 dl 1.52 private void addWorker() {
1081     Throwable ex = null;
1082     ForkJoinWorkerThread t = null;
1083     try {
1084     t = factory.newThread(this);
1085     } catch (Throwable e) {
1086     ex = e;
1087     }
1088     if (t == null) { // null or exceptional factory return
1089     long c; // adjust counts
1090     do {} while (!UNSAFE.compareAndSwapLong
1091     (this, ctlOffset, c = ctl,
1092     (((c - AC_UNIT) & AC_MASK) |
1093     ((c - TC_UNIT) & TC_MASK) |
1094     (c & ~(AC_MASK|TC_MASK)))));
1095     // Propagate exception if originating from an external caller
1096     if (!tryTerminate(false) && ex != null &&
1097     !(Thread.currentThread() instanceof ForkJoinWorkerThread))
1098     UNSAFE.throwException(ex);
1099     }
1100     else
1101     t.start();
1102 dl 1.14 }
1103    
1104     /**
1105 dl 1.52 * Callback from ForkJoinWorkerThread constructor to assign a
1106     * public name
1107 dl 1.14 */
1108 dl 1.52 final String nextWorkerName() {
1109     for (int n;;) {
1110     if (UNSAFE.compareAndSwapInt(this, nextWorkerNumberOffset,
1111     n = nextWorkerNumber, ++n))
1112     return workerNamePrefix + n;
1113 dl 1.14 }
1114     }
1115    
1116     /**
1117 dl 1.52 * Callback from ForkJoinWorkerThread constructor to
1118     * determine its poolIndex and record in workers array.
1119 dl 1.17 *
1120 dl 1.52 * @param w the worker
1121     * @return the worker's pool index
1122 dl 1.14 */
1123 dl 1.52 final int registerWorker(ForkJoinWorkerThread w) {
1124     /*
1125     * In the typical case, a new worker acquires the lock, uses
1126     * next available index and returns quickly. Since we should
1127     * not block callers (ultimately from signalWork or
1128     * tryPreBlock) waiting for the lock needed to do this, we
1129     * instead help release other workers while waiting for the
1130     * lock.
1131     */
1132     for (int g;;) {
1133     ForkJoinWorkerThread[] ws;
1134     if (((g = scanGuard) & SG_UNIT) == 0 &&
1135     UNSAFE.compareAndSwapInt(this, scanGuardOffset,
1136     g, g | SG_UNIT)) {
1137     int k = nextWorkerIndex;
1138     try {
1139     if ((ws = workers) != null) { // ignore on shutdown
1140     int n = ws.length;
1141     if (k < 0 || k >= n || ws[k] != null) {
1142     for (k = 0; k < n && ws[k] != null; ++k)
1143     ;
1144     if (k == n)
1145     ws = workers = Arrays.copyOf(ws, n << 1);
1146     }
1147     ws[k] = w;
1148     nextWorkerIndex = k + 1;
1149     int m = g & SMASK;
1150 jsr166 1.63 g = (k > m) ? ((m << 1) + 1) & SMASK : g + (SG_UNIT<<1);
1151 dl 1.52 }
1152     } finally {
1153     scanGuard = g;
1154     }
1155     return k;
1156 dl 1.41 }
1157 dl 1.52 else if ((ws = workers) != null) { // help release others
1158     for (ForkJoinWorkerThread u : ws) {
1159     if (u != null && u.queueBase != u.queueTop) {
1160     if (tryReleaseWaiter())
1161 dl 1.45 break;
1162 dl 1.43 }
1163     }
1164 dl 1.14 }
1165     }
1166     }
1167    
1168     /**
1169 dl 1.52 * Final callback from terminating worker. Removes record of
1170     * worker from array, and adjusts counts. If pool is shutting
1171     * down, tries to complete termination.
1172     *
1173     * @param w the worker
1174 dl 1.14 */
1175 dl 1.52 final void deregisterWorker(ForkJoinWorkerThread w, Throwable ex) {
1176     int idx = w.poolIndex;
1177     int sc = w.stealCount;
1178     int steps = 0;
1179     // Remove from array, adjust worker counts and collect steal count.
1180     // We can intermix failed removes or adjusts with steal updates
1181     do {
1182     long s, c;
1183     int g;
1184     if (steps == 0 && ((g = scanGuard) & SG_UNIT) == 0 &&
1185     UNSAFE.compareAndSwapInt(this, scanGuardOffset,
1186     g, g |= SG_UNIT)) {
1187     ForkJoinWorkerThread[] ws = workers;
1188     if (ws != null && idx >= 0 &&
1189     idx < ws.length && ws[idx] == w)
1190     ws[idx] = null; // verify
1191     nextWorkerIndex = idx;
1192     scanGuard = g + SG_UNIT;
1193     steps = 1;
1194 dl 1.18 }
1195 dl 1.52 if (steps == 1 &&
1196     UNSAFE.compareAndSwapLong(this, ctlOffset, c = ctl,
1197     (((c - AC_UNIT) & AC_MASK) |
1198     ((c - TC_UNIT) & TC_MASK) |
1199     (c & ~(AC_MASK|TC_MASK)))))
1200     steps = 2;
1201     if (sc != 0 &&
1202     UNSAFE.compareAndSwapLong(this, stealCountOffset,
1203     s = stealCount, s + sc))
1204     sc = 0;
1205     } while (steps != 2 || sc != 0);
1206     if (!tryTerminate(false)) {
1207     if (ex != null) // possibly replace if died abnormally
1208     signalWork();
1209     else
1210     tryReleaseWaiter();
1211 dl 1.14 }
1212 dl 1.19 }
1213 dl 1.15
1214 dl 1.52 // Shutdown and termination
1215    
1216 dl 1.15 /**
1217 dl 1.14 * Possibly initiates and/or completes termination.
1218     *
1219     * @param now if true, unconditionally terminate, else only
1220     * if shutdown and empty queue and no active workers
1221     * @return true if now terminating or terminated
1222 jsr166 1.1 */
1223 dl 1.14 private boolean tryTerminate(boolean now) {
1224 dl 1.52 long c;
1225     while (((c = ctl) & STOP_BIT) == 0) {
1226     if (!now) {
1227     if ((int)(c >> AC_SHIFT) != -parallelism)
1228     return false;
1229     if (!shutdown || blockedCount != 0 || quiescerCount != 0 ||
1230 dl 1.56 queueBase != queueTop) {
1231 dl 1.52 if (ctl == c) // staleness check
1232     return false;
1233     continue;
1234     }
1235     }
1236     if (UNSAFE.compareAndSwapLong(this, ctlOffset, c, c | STOP_BIT))
1237     startTerminating();
1238     }
1239 dl 1.56 if ((short)(c >>> TC_SHIFT) == -parallelism) { // signal when 0 workers
1240     final ReentrantLock lock = this.submissionLock;
1241     lock.lock();
1242     try {
1243     termination.signalAll();
1244     } finally {
1245     lock.unlock();
1246     }
1247 dl 1.14 }
1248 jsr166 1.1 return true;
1249     }
1250    
1251     /**
1252 dl 1.52 * Runs up to three passes through workers: (0) Setting
1253 dl 1.56 * termination status for each worker, followed by wakeups up to
1254     * queued workers; (1) helping cancel tasks; (2) interrupting
1255 dl 1.52 * lagging threads (likely in external tasks, but possibly also
1256     * blocked in joins). Each pass repeats previous steps because of
1257     * potential lagging thread creation.
1258 dl 1.14 */
1259     private void startTerminating() {
1260 dl 1.19 cancelSubmissions();
1261 dl 1.52 for (int pass = 0; pass < 3; ++pass) {
1262     ForkJoinWorkerThread[] ws = workers;
1263     if (ws != null) {
1264     for (ForkJoinWorkerThread w : ws) {
1265     if (w != null) {
1266     w.terminate = true;
1267     if (pass > 0) {
1268     w.cancelTasks();
1269     if (pass > 1 && !w.isInterrupted()) {
1270     try {
1271     w.interrupt();
1272     } catch (SecurityException ignore) {
1273     }
1274 dl 1.19 }
1275     }
1276     }
1277     }
1278 dl 1.52 terminateWaiters();
1279 dl 1.19 }
1280 dl 1.17 }
1281     }
1282    
1283     /**
1284 dl 1.52 * Polls and cancels all submissions. Called only during termination.
1285 dl 1.17 */
1286     private void cancelSubmissions() {
1287 dl 1.52 while (queueBase != queueTop) {
1288     ForkJoinTask<?> task = pollSubmission();
1289     if (task != null) {
1290     try {
1291     task.cancel(false);
1292     } catch (Throwable ignore) {
1293     }
1294 dl 1.14 }
1295     }
1296 dl 1.17 }
1297    
1298 dl 1.52 /**
1299     * Tries to set the termination status of waiting workers, and
1300 dl 1.56 * then wakes them up (after which they will terminate).
1301 dl 1.52 */
1302     private void terminateWaiters() {
1303     ForkJoinWorkerThread[] ws = workers;
1304     if (ws != null) {
1305     ForkJoinWorkerThread w; long c; int i, e;
1306     int n = ws.length;
1307     while ((i = ~(e = (int)(c = ctl)) & SMASK) < n &&
1308     (w = ws[i]) != null && w.eventCount == (e & E_MASK)) {
1309     if (UNSAFE.compareAndSwapLong(this, ctlOffset, c,
1310     (long)(w.nextWait & E_MASK) |
1311     ((c + AC_UNIT) & AC_MASK) |
1312     (c & (TC_MASK|STOP_BIT)))) {
1313     w.terminate = true;
1314     w.eventCount = e + EC_UNIT;
1315     if (w.parked)
1316     UNSAFE.unpark(w);
1317     }
1318     }
1319     }
1320     }
1321    
1322     // misc ForkJoinWorkerThread support
1323 dl 1.14
1324     /**
1325 dl 1.52 * Increment or decrement quiescerCount. Needed only to prevent
1326     * triggering shutdown if a worker is transiently inactive while
1327     * checking quiescence.
1328     *
1329     * @param delta 1 for increment, -1 for decrement
1330 jsr166 1.1 */
1331 dl 1.52 final void addQuiescerCount(int delta) {
1332     int c;
1333 jsr166 1.63 do {} while (!UNSAFE.compareAndSwapInt(this, quiescerCountOffset,
1334     c = quiescerCount, c + delta));
1335 jsr166 1.1 }
1336    
1337     /**
1338 dl 1.52 * Directly increment or decrement active count without
1339     * queuing. This method is used to transiently assert inactivation
1340     * while checking quiescence.
1341 dl 1.19 *
1342 dl 1.52 * @param delta 1 for increment, -1 for decrement
1343 jsr166 1.1 */
1344 dl 1.52 final void addActiveCount(int delta) {
1345     long d = delta < 0 ? -AC_UNIT : AC_UNIT;
1346     long c;
1347     do {} while (!UNSAFE.compareAndSwapLong(this, ctlOffset, c = ctl,
1348     ((c + d) & AC_MASK) |
1349     (c & ~AC_MASK)));
1350 jsr166 1.1 }
1351    
1352     /**
1353 dl 1.14 * Returns the approximate (non-atomic) number of idle threads per
1354     * active thread.
1355     */
1356     final int idlePerActive() {
1357 dl 1.52 // Approximate at powers of two for small values, saturate past 4
1358     int p = parallelism;
1359 jsr166 1.63 int a = p + (int)(ctl >> AC_SHIFT);
1360     return (a > (p >>>= 1) ? 0 :
1361     a > (p >>>= 1) ? 1 :
1362     a > (p >>>= 1) ? 2 :
1363     a > (p >>>= 1) ? 4 :
1364     8);
1365 dl 1.14 }
1366    
1367 dl 1.52 // Exported methods
1368 jsr166 1.1
1369     // Constructors
1370    
1371     /**
1372 jsr166 1.9 * Creates a {@code ForkJoinPool} with parallelism equal to {@link
1373 dl 1.18 * java.lang.Runtime#availableProcessors}, using the {@linkplain
1374     * #defaultForkJoinWorkerThreadFactory default thread factory},
1375     * no UncaughtExceptionHandler, and non-async LIFO processing mode.
1376 jsr166 1.1 *
1377     * @throws SecurityException if a security manager exists and
1378     * the caller is not permitted to modify threads
1379     * because it does not hold {@link
1380     * java.lang.RuntimePermission}{@code ("modifyThread")}
1381     */
1382     public ForkJoinPool() {
1383     this(Runtime.getRuntime().availableProcessors(),
1384 dl 1.18 defaultForkJoinWorkerThreadFactory, null, false);
1385 jsr166 1.1 }
1386    
1387     /**
1388 jsr166 1.9 * Creates a {@code ForkJoinPool} with the indicated parallelism
1389 dl 1.18 * level, the {@linkplain
1390     * #defaultForkJoinWorkerThreadFactory default thread factory},
1391     * no UncaughtExceptionHandler, and non-async LIFO processing mode.
1392 jsr166 1.1 *
1393 jsr166 1.9 * @param parallelism the parallelism level
1394 jsr166 1.1 * @throws IllegalArgumentException if parallelism less than or
1395 jsr166 1.11 * equal to zero, or greater than implementation limit
1396 jsr166 1.1 * @throws SecurityException if a security manager exists and
1397     * the caller is not permitted to modify threads
1398     * because it does not hold {@link
1399     * java.lang.RuntimePermission}{@code ("modifyThread")}
1400     */
1401     public ForkJoinPool(int parallelism) {
1402 dl 1.18 this(parallelism, defaultForkJoinWorkerThreadFactory, null, false);
1403 jsr166 1.1 }
1404    
1405     /**
1406 dl 1.18 * Creates a {@code ForkJoinPool} with the given parameters.
1407 jsr166 1.1 *
1408 dl 1.18 * @param parallelism the parallelism level. For default value,
1409     * use {@link java.lang.Runtime#availableProcessors}.
1410     * @param factory the factory for creating new threads. For default value,
1411     * use {@link #defaultForkJoinWorkerThreadFactory}.
1412 dl 1.19 * @param handler the handler for internal worker threads that
1413     * terminate due to unrecoverable errors encountered while executing
1414 jsr166 1.31 * tasks. For default value, use {@code null}.
1415 dl 1.19 * @param asyncMode if true,
1416 dl 1.18 * establishes local first-in-first-out scheduling mode for forked
1417     * tasks that are never joined. This mode may be more appropriate
1418     * than default locally stack-based mode in applications in which
1419     * worker threads only process event-style asynchronous tasks.
1420 jsr166 1.31 * For default value, use {@code false}.
1421 jsr166 1.1 * @throws IllegalArgumentException if parallelism less than or
1422 jsr166 1.11 * equal to zero, or greater than implementation limit
1423     * @throws NullPointerException if the factory is null
1424 jsr166 1.1 * @throws SecurityException if a security manager exists and
1425     * the caller is not permitted to modify threads
1426     * because it does not hold {@link
1427     * java.lang.RuntimePermission}{@code ("modifyThread")}
1428     */
1429 dl 1.19 public ForkJoinPool(int parallelism,
1430 dl 1.18 ForkJoinWorkerThreadFactory factory,
1431     Thread.UncaughtExceptionHandler handler,
1432     boolean asyncMode) {
1433 dl 1.14 checkPermission();
1434     if (factory == null)
1435     throw new NullPointerException();
1436 dl 1.52 if (parallelism <= 0 || parallelism > MAX_ID)
1437 jsr166 1.1 throw new IllegalArgumentException();
1438 dl 1.14 this.parallelism = parallelism;
1439 jsr166 1.1 this.factory = factory;
1440 dl 1.18 this.ueh = handler;
1441     this.locallyFifo = asyncMode;
1442 dl 1.52 long np = (long)(-parallelism); // offset ctl counts
1443     this.ctl = ((np << AC_SHIFT) & AC_MASK) | ((np << TC_SHIFT) & TC_MASK);
1444     this.submissionQueue = new ForkJoinTask<?>[INITIAL_QUEUE_CAPACITY];
1445     // initialize workers array with room for 2*parallelism if possible
1446     int n = parallelism << 1;
1447     if (n >= MAX_ID)
1448     n = MAX_ID;
1449     else { // See Hackers Delight, sec 3.2, where n < (1 << 16)
1450     n |= n >>> 1; n |= n >>> 2; n |= n >>> 4; n |= n >>> 8;
1451     }
1452     workers = new ForkJoinWorkerThread[n + 1];
1453     this.submissionLock = new ReentrantLock();
1454     this.termination = submissionLock.newCondition();
1455     StringBuilder sb = new StringBuilder("ForkJoinPool-");
1456     sb.append(poolNumberGenerator.incrementAndGet());
1457     sb.append("-worker-");
1458     this.workerNamePrefix = sb.toString();
1459 jsr166 1.1 }
1460    
1461     // Execution methods
1462    
1463     /**
1464     * Performs the given task, returning its result upon completion.
1465 dl 1.52 * If the computation encounters an unchecked Exception or Error,
1466     * it is rethrown as the outcome of this invocation. Rethrown
1467     * exceptions behave in the same way as regular exceptions, but,
1468     * when possible, contain stack traces (as displayed for example
1469     * using {@code ex.printStackTrace()}) of both the current thread
1470     * as well as the thread actually encountering the exception;
1471     * minimally only the latter.
1472 jsr166 1.1 *
1473     * @param task the task
1474     * @return the task's result
1475 jsr166 1.11 * @throws NullPointerException if the task is null
1476     * @throws RejectedExecutionException if the task cannot be
1477     * scheduled for execution
1478 jsr166 1.1 */
1479     public <T> T invoke(ForkJoinTask<T> task) {
1480 dl 1.52 Thread t = Thread.currentThread();
1481 dl 1.41 if (task == null)
1482     throw new NullPointerException();
1483 dl 1.52 if (shutdown)
1484 dl 1.41 throw new RejectedExecutionException();
1485     if ((t instanceof ForkJoinWorkerThread) &&
1486     ((ForkJoinWorkerThread)t).pool == this)
1487     return task.invoke(); // bypass submit if in same pool
1488     else {
1489 dl 1.52 addSubmission(task);
1490 dl 1.41 return task.join();
1491     }
1492     }
1493    
1494     /**
1495     * Unless terminating, forks task if within an ongoing FJ
1496     * computation in the current pool, else submits as external task.
1497     */
1498     private <T> void forkOrSubmit(ForkJoinTask<T> task) {
1499 dl 1.52 ForkJoinWorkerThread w;
1500     Thread t = Thread.currentThread();
1501     if (shutdown)
1502 dl 1.41 throw new RejectedExecutionException();
1503     if ((t instanceof ForkJoinWorkerThread) &&
1504 dl 1.52 (w = (ForkJoinWorkerThread)t).pool == this)
1505     w.pushTask(task);
1506 dl 1.41 else
1507 dl 1.52 addSubmission(task);
1508 jsr166 1.1 }
1509    
1510     /**
1511     * Arranges for (asynchronous) execution of the given task.
1512     *
1513     * @param task the task
1514 jsr166 1.11 * @throws NullPointerException if the task is null
1515     * @throws RejectedExecutionException if the task cannot be
1516     * scheduled for execution
1517 jsr166 1.1 */
1518 jsr166 1.8 public void execute(ForkJoinTask<?> task) {
1519 dl 1.41 if (task == null)
1520     throw new NullPointerException();
1521     forkOrSubmit(task);
1522 jsr166 1.1 }
1523    
1524     // AbstractExecutorService methods
1525    
1526 jsr166 1.11 /**
1527     * @throws NullPointerException if the task is null
1528     * @throws RejectedExecutionException if the task cannot be
1529     * scheduled for execution
1530     */
1531 jsr166 1.1 public void execute(Runnable task) {
1532 dl 1.41 if (task == null)
1533     throw new NullPointerException();
1534 jsr166 1.2 ForkJoinTask<?> job;
1535 jsr166 1.3 if (task instanceof ForkJoinTask<?>) // avoid re-wrap
1536     job = (ForkJoinTask<?>) task;
1537 jsr166 1.2 else
1538 jsr166 1.7 job = ForkJoinTask.adapt(task, null);
1539 dl 1.41 forkOrSubmit(job);
1540 jsr166 1.1 }
1541    
1542 jsr166 1.11 /**
1543 dl 1.18 * Submits a ForkJoinTask for execution.
1544     *
1545     * @param task the task to submit
1546     * @return the task
1547     * @throws NullPointerException if the task is null
1548     * @throws RejectedExecutionException if the task cannot be
1549     * scheduled for execution
1550     */
1551     public <T> ForkJoinTask<T> submit(ForkJoinTask<T> task) {
1552 dl 1.41 if (task == null)
1553     throw new NullPointerException();
1554     forkOrSubmit(task);
1555 dl 1.18 return task;
1556     }
1557    
1558     /**
1559 jsr166 1.11 * @throws NullPointerException if the task is null
1560     * @throws RejectedExecutionException if the task cannot be
1561     * scheduled for execution
1562     */
1563 jsr166 1.1 public <T> ForkJoinTask<T> submit(Callable<T> task) {
1564 dl 1.41 if (task == null)
1565     throw new NullPointerException();
1566 jsr166 1.7 ForkJoinTask<T> job = ForkJoinTask.adapt(task);
1567 dl 1.41 forkOrSubmit(job);
1568 jsr166 1.1 return job;
1569     }
1570    
1571 jsr166 1.11 /**
1572     * @throws NullPointerException if the task is null
1573     * @throws RejectedExecutionException if the task cannot be
1574     * scheduled for execution
1575     */
1576 jsr166 1.1 public <T> ForkJoinTask<T> submit(Runnable task, T result) {
1577 dl 1.41 if (task == null)
1578     throw new NullPointerException();
1579 jsr166 1.7 ForkJoinTask<T> job = ForkJoinTask.adapt(task, result);
1580 dl 1.41 forkOrSubmit(job);
1581 jsr166 1.1 return job;
1582     }
1583    
1584 jsr166 1.11 /**
1585     * @throws NullPointerException if the task is null
1586     * @throws RejectedExecutionException if the task cannot be
1587     * scheduled for execution
1588     */
1589 jsr166 1.1 public ForkJoinTask<?> submit(Runnable task) {
1590 dl 1.41 if (task == null)
1591     throw new NullPointerException();
1592 jsr166 1.2 ForkJoinTask<?> job;
1593 jsr166 1.3 if (task instanceof ForkJoinTask<?>) // avoid re-wrap
1594     job = (ForkJoinTask<?>) task;
1595 jsr166 1.2 else
1596 jsr166 1.7 job = ForkJoinTask.adapt(task, null);
1597 dl 1.41 forkOrSubmit(job);
1598 jsr166 1.1 return job;
1599     }
1600    
1601     /**
1602 jsr166 1.11 * @throws NullPointerException {@inheritDoc}
1603     * @throws RejectedExecutionException {@inheritDoc}
1604     */
1605 jsr166 1.1 public <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) {
1606     ArrayList<ForkJoinTask<T>> forkJoinTasks =
1607     new ArrayList<ForkJoinTask<T>>(tasks.size());
1608     for (Callable<T> task : tasks)
1609 jsr166 1.7 forkJoinTasks.add(ForkJoinTask.adapt(task));
1610 jsr166 1.1 invoke(new InvokeAll<T>(forkJoinTasks));
1611    
1612     @SuppressWarnings({"unchecked", "rawtypes"})
1613 dl 1.15 List<Future<T>> futures = (List<Future<T>>) (List) forkJoinTasks;
1614 jsr166 1.1 return futures;
1615     }
1616    
1617     static final class InvokeAll<T> extends RecursiveAction {
1618     final ArrayList<ForkJoinTask<T>> tasks;
1619     InvokeAll(ArrayList<ForkJoinTask<T>> tasks) { this.tasks = tasks; }
1620     public void compute() {
1621     try { invokeAll(tasks); }
1622     catch (Exception ignore) {}
1623     }
1624     private static final long serialVersionUID = -7914297376763021607L;
1625     }
1626    
1627     /**
1628     * Returns the factory used for constructing new workers.
1629     *
1630     * @return the factory used for constructing new workers
1631     */
1632     public ForkJoinWorkerThreadFactory getFactory() {
1633     return factory;
1634     }
1635    
1636     /**
1637     * Returns the handler for internal worker threads that terminate
1638     * due to unrecoverable errors encountered while executing tasks.
1639     *
1640 jsr166 1.4 * @return the handler, or {@code null} if none
1641 jsr166 1.1 */
1642     public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler() {
1643 dl 1.14 return ueh;
1644 jsr166 1.1 }
1645    
1646     /**
1647 jsr166 1.9 * Returns the targeted parallelism level of this pool.
1648 jsr166 1.1 *
1649 jsr166 1.9 * @return the targeted parallelism level of this pool
1650 jsr166 1.1 */
1651     public int getParallelism() {
1652     return parallelism;
1653     }
1654    
1655     /**
1656     * Returns the number of worker threads that have started but not
1657 jsr166 1.34 * yet terminated. The result returned by this method may differ
1658 jsr166 1.4 * from {@link #getParallelism} when threads are created to
1659 jsr166 1.1 * maintain parallelism when others are cooperatively blocked.
1660     *
1661     * @return the number of worker threads
1662     */
1663     public int getPoolSize() {
1664 dl 1.52 return parallelism + (short)(ctl >>> TC_SHIFT);
1665 jsr166 1.1 }
1666    
1667     /**
1668 jsr166 1.4 * Returns {@code true} if this pool uses local first-in-first-out
1669 jsr166 1.1 * scheduling mode for forked tasks that are never joined.
1670     *
1671 jsr166 1.4 * @return {@code true} if this pool uses async mode
1672 jsr166 1.1 */
1673     public boolean getAsyncMode() {
1674     return locallyFifo;
1675     }
1676    
1677     /**
1678     * Returns an estimate of the number of worker threads that are
1679     * not blocked waiting to join tasks or for other managed
1680 dl 1.14 * synchronization. This method may overestimate the
1681     * number of running threads.
1682 jsr166 1.1 *
1683     * @return the number of worker threads
1684     */
1685     public int getRunningThreadCount() {
1686 dl 1.52 int r = parallelism + (int)(ctl >> AC_SHIFT);
1687 jsr166 1.63 return (r <= 0) ? 0 : r; // suppress momentarily negative values
1688 jsr166 1.1 }
1689    
1690     /**
1691     * Returns an estimate of the number of threads that are currently
1692     * stealing or executing tasks. This method may overestimate the
1693     * number of active threads.
1694     *
1695     * @return the number of active threads
1696     */
1697     public int getActiveThreadCount() {
1698 dl 1.52 int r = parallelism + (int)(ctl >> AC_SHIFT) + blockedCount;
1699 jsr166 1.63 return (r <= 0) ? 0 : r; // suppress momentarily negative values
1700 jsr166 1.1 }
1701    
1702     /**
1703 jsr166 1.4 * Returns {@code true} if all worker threads are currently idle.
1704     * An idle worker is one that cannot obtain a task to execute
1705     * because none are available to steal from other threads, and
1706     * there are no pending submissions to the pool. This method is
1707     * conservative; it might not return {@code true} immediately upon
1708     * idleness of all threads, but will eventually become true if
1709     * threads remain inactive.
1710 jsr166 1.1 *
1711 jsr166 1.4 * @return {@code true} if all threads are currently idle
1712 jsr166 1.1 */
1713     public boolean isQuiescent() {
1714 dl 1.52 return parallelism + (int)(ctl >> AC_SHIFT) + blockedCount == 0;
1715 jsr166 1.1 }
1716    
1717     /**
1718     * Returns an estimate of the total number of tasks stolen from
1719     * one thread's work queue by another. The reported value
1720     * underestimates the actual total number of steals when the pool
1721     * is not quiescent. This value may be useful for monitoring and
1722     * tuning fork/join programs: in general, steal counts should be
1723     * high enough to keep threads busy, but low enough to avoid
1724     * overhead and contention across threads.
1725     *
1726     * @return the number of steals
1727     */
1728     public long getStealCount() {
1729 dl 1.14 return stealCount;
1730 jsr166 1.1 }
1731    
1732     /**
1733     * Returns an estimate of the total number of tasks currently held
1734     * in queues by worker threads (but not including tasks submitted
1735     * to the pool that have not begun executing). This value is only
1736     * an approximation, obtained by iterating across all threads in
1737     * the pool. This method may be useful for tuning task
1738     * granularities.
1739     *
1740     * @return the number of queued tasks
1741     */
1742     public long getQueuedTaskCount() {
1743     long count = 0;
1744 dl 1.52 ForkJoinWorkerThread[] ws;
1745     if ((short)(ctl >>> TC_SHIFT) > -parallelism &&
1746     (ws = workers) != null) {
1747     for (ForkJoinWorkerThread w : ws)
1748     if (w != null)
1749     count -= w.queueBase - w.queueTop; // must read base first
1750     }
1751 jsr166 1.1 return count;
1752     }
1753    
1754     /**
1755 jsr166 1.8 * Returns an estimate of the number of tasks submitted to this
1756 dl 1.55 * pool that have not yet begun executing. This method may take
1757 dl 1.52 * time proportional to the number of submissions.
1758 jsr166 1.1 *
1759     * @return the number of queued submissions
1760     */
1761     public int getQueuedSubmissionCount() {
1762 dl 1.52 return -queueBase + queueTop;
1763 jsr166 1.1 }
1764    
1765     /**
1766 jsr166 1.4 * Returns {@code true} if there are any tasks submitted to this
1767     * pool that have not yet begun executing.
1768 jsr166 1.1 *
1769     * @return {@code true} if there are any queued submissions
1770     */
1771     public boolean hasQueuedSubmissions() {
1772 dl 1.52 return queueBase != queueTop;
1773 jsr166 1.1 }
1774    
1775     /**
1776     * Removes and returns the next unexecuted submission if one is
1777     * available. This method may be useful in extensions to this
1778     * class that re-assign work in systems with multiple pools.
1779     *
1780 jsr166 1.4 * @return the next submission, or {@code null} if none
1781 jsr166 1.1 */
1782     protected ForkJoinTask<?> pollSubmission() {
1783 dl 1.52 ForkJoinTask<?> t; ForkJoinTask<?>[] q; int b, i;
1784     while ((b = queueBase) != queueTop &&
1785     (q = submissionQueue) != null &&
1786     (i = (q.length - 1) & b) >= 0) {
1787     long u = (i << ASHIFT) + ABASE;
1788     if ((t = q[i]) != null &&
1789     queueBase == b &&
1790     UNSAFE.compareAndSwapObject(q, u, t, null)) {
1791     queueBase = b + 1;
1792     return t;
1793     }
1794     }
1795     return null;
1796 jsr166 1.1 }
1797    
1798     /**
1799     * Removes all available unexecuted submitted and forked tasks
1800     * from scheduling queues and adds them to the given collection,
1801     * without altering their execution status. These may include
1802 jsr166 1.8 * artificially generated or wrapped tasks. This method is
1803     * designed to be invoked only when the pool is known to be
1804 jsr166 1.1 * quiescent. Invocations at other times may not remove all
1805     * tasks. A failure encountered while attempting to add elements
1806     * to collection {@code c} may result in elements being in
1807     * neither, either or both collections when the associated
1808     * exception is thrown. The behavior of this operation is
1809     * undefined if the specified collection is modified while the
1810     * operation is in progress.
1811     *
1812     * @param c the collection to transfer elements into
1813     * @return the number of elements transferred
1814     */
1815 jsr166 1.5 protected int drainTasksTo(Collection<? super ForkJoinTask<?>> c) {
1816 dl 1.52 int count = 0;
1817     while (queueBase != queueTop) {
1818     ForkJoinTask<?> t = pollSubmission();
1819     if (t != null) {
1820     c.add(t);
1821     ++count;
1822     }
1823     }
1824     ForkJoinWorkerThread[] ws;
1825     if ((short)(ctl >>> TC_SHIFT) > -parallelism &&
1826     (ws = workers) != null) {
1827     for (ForkJoinWorkerThread w : ws)
1828     if (w != null)
1829     count += w.drainTasksTo(c);
1830     }
1831 dl 1.18 return count;
1832     }
1833    
1834     /**
1835 jsr166 1.1 * Returns a string identifying this pool, as well as its state,
1836     * including indications of run state, parallelism level, and
1837     * worker and task counts.
1838     *
1839     * @return a string identifying this pool, as well as its state
1840     */
1841     public String toString() {
1842     long st = getStealCount();
1843     long qt = getQueuedTaskCount();
1844     long qs = getQueuedSubmissionCount();
1845 dl 1.14 int pc = parallelism;
1846 dl 1.52 long c = ctl;
1847     int tc = pc + (short)(c >>> TC_SHIFT);
1848     int rc = pc + (int)(c >> AC_SHIFT);
1849     if (rc < 0) // ignore transient negative
1850     rc = 0;
1851     int ac = rc + blockedCount;
1852     String level;
1853     if ((c & STOP_BIT) != 0)
1854 jsr166 1.63 level = (tc == 0) ? "Terminated" : "Terminating";
1855 dl 1.52 else
1856 jsr166 1.63 level = shutdown ? "Shutting down" : "Running";
1857 jsr166 1.1 return super.toString() +
1858 dl 1.52 "[" + level +
1859 dl 1.14 ", parallelism = " + pc +
1860     ", size = " + tc +
1861     ", active = " + ac +
1862     ", running = " + rc +
1863 jsr166 1.1 ", steals = " + st +
1864     ", tasks = " + qt +
1865     ", submissions = " + qs +
1866     "]";
1867     }
1868    
1869     /**
1870     * Initiates an orderly shutdown in which previously submitted
1871     * tasks are executed, but no new tasks will be accepted.
1872     * Invocation has no additional effect if already shut down.
1873     * Tasks that are in the process of being submitted concurrently
1874     * during the course of this method may or may not be rejected.
1875     *
1876     * @throws SecurityException if a security manager exists and
1877     * the caller is not permitted to modify threads
1878     * because it does not hold {@link
1879     * java.lang.RuntimePermission}{@code ("modifyThread")}
1880     */
1881     public void shutdown() {
1882     checkPermission();
1883 dl 1.52 shutdown = true;
1884 dl 1.14 tryTerminate(false);
1885 jsr166 1.1 }
1886    
1887     /**
1888 jsr166 1.9 * Attempts to cancel and/or stop all tasks, and reject all
1889     * subsequently submitted tasks. Tasks that are in the process of
1890     * being submitted or executed concurrently during the course of
1891     * this method may or may not be rejected. This method cancels
1892     * both existing and unexecuted tasks, in order to permit
1893     * termination in the presence of task dependencies. So the method
1894     * always returns an empty list (unlike the case for some other
1895     * Executors).
1896 jsr166 1.1 *
1897     * @return an empty list
1898     * @throws SecurityException if a security manager exists and
1899     * the caller is not permitted to modify threads
1900     * because it does not hold {@link
1901     * java.lang.RuntimePermission}{@code ("modifyThread")}
1902     */
1903     public List<Runnable> shutdownNow() {
1904     checkPermission();
1905 dl 1.52 shutdown = true;
1906 dl 1.14 tryTerminate(true);
1907 jsr166 1.1 return Collections.emptyList();
1908     }
1909    
1910     /**
1911     * Returns {@code true} if all tasks have completed following shut down.
1912     *
1913     * @return {@code true} if all tasks have completed following shut down
1914     */
1915     public boolean isTerminated() {
1916 dl 1.52 long c = ctl;
1917     return ((c & STOP_BIT) != 0L &&
1918     (short)(c >>> TC_SHIFT) == -parallelism);
1919 jsr166 1.1 }
1920    
1921     /**
1922     * Returns {@code true} if the process of termination has
1923 jsr166 1.9 * commenced but not yet completed. This method may be useful for
1924     * debugging. A return of {@code true} reported a sufficient
1925     * period after shutdown may indicate that submitted tasks have
1926 dl 1.49 * ignored or suppressed interruption, or are waiting for IO,
1927     * causing this executor not to properly terminate. (See the
1928     * advisory notes for class {@link ForkJoinTask} stating that
1929     * tasks should not normally entail blocking operations. But if
1930     * they do, they must abort them on interrupt.)
1931 jsr166 1.1 *
1932 jsr166 1.9 * @return {@code true} if terminating but not yet terminated
1933 jsr166 1.1 */
1934     public boolean isTerminating() {
1935 dl 1.52 long c = ctl;
1936     return ((c & STOP_BIT) != 0L &&
1937     (short)(c >>> TC_SHIFT) != -parallelism);
1938 jsr166 1.1 }
1939    
1940     /**
1941 dl 1.39 * Returns true if terminating or terminated. Used by ForkJoinWorkerThread.
1942     */
1943     final boolean isAtLeastTerminating() {
1944 dl 1.52 return (ctl & STOP_BIT) != 0L;
1945 dl 1.39 }
1946 jsr166 1.40
1947 dl 1.39 /**
1948 jsr166 1.1 * Returns {@code true} if this pool has been shut down.
1949     *
1950     * @return {@code true} if this pool has been shut down
1951     */
1952     public boolean isShutdown() {
1953 dl 1.52 return shutdown;
1954 jsr166 1.9 }
1955    
1956     /**
1957 jsr166 1.1 * Blocks until all tasks have completed execution after a shutdown
1958     * request, or the timeout occurs, or the current thread is
1959     * interrupted, whichever happens first.
1960     *
1961     * @param timeout the maximum time to wait
1962     * @param unit the time unit of the timeout argument
1963     * @return {@code true} if this executor terminated and
1964     * {@code false} if the timeout elapsed before termination
1965     * @throws InterruptedException if interrupted while waiting
1966     */
1967     public boolean awaitTermination(long timeout, TimeUnit unit)
1968     throws InterruptedException {
1969 dl 1.52 long nanos = unit.toNanos(timeout);
1970     final ReentrantLock lock = this.submissionLock;
1971     lock.lock();
1972 dl 1.18 try {
1973 dl 1.52 for (;;) {
1974     if (isTerminated())
1975     return true;
1976     if (nanos <= 0)
1977     return false;
1978     nanos = termination.awaitNanos(nanos);
1979     }
1980     } finally {
1981     lock.unlock();
1982 dl 1.18 }
1983 jsr166 1.1 }
1984    
1985     /**
1986     * Interface for extending managed parallelism for tasks running
1987 jsr166 1.8 * in {@link ForkJoinPool}s.
1988     *
1989 dl 1.19 * <p>A {@code ManagedBlocker} provides two methods. Method
1990     * {@code isReleasable} must return {@code true} if blocking is
1991     * not necessary. Method {@code block} blocks the current thread
1992     * if necessary (perhaps internally invoking {@code isReleasable}
1993 dl 1.54 * before actually blocking). These actions are performed by any
1994     * thread invoking {@link ForkJoinPool#managedBlock}. The
1995     * unusual methods in this API accommodate synchronizers that may,
1996     * but don't usually, block for long periods. Similarly, they
1997     * allow more efficient internal handling of cases in which
1998     * additional workers may be, but usually are not, needed to
1999     * ensure sufficient parallelism. Toward this end,
2000     * implementations of method {@code isReleasable} must be amenable
2001     * to repeated invocation.
2002 jsr166 1.1 *
2003     * <p>For example, here is a ManagedBlocker based on a
2004     * ReentrantLock:
2005     * <pre> {@code
2006     * class ManagedLocker implements ManagedBlocker {
2007     * final ReentrantLock lock;
2008     * boolean hasLock = false;
2009     * ManagedLocker(ReentrantLock lock) { this.lock = lock; }
2010     * public boolean block() {
2011     * if (!hasLock)
2012     * lock.lock();
2013     * return true;
2014     * }
2015     * public boolean isReleasable() {
2016     * return hasLock || (hasLock = lock.tryLock());
2017     * }
2018     * }}</pre>
2019 dl 1.19 *
2020     * <p>Here is a class that possibly blocks waiting for an
2021     * item on a given queue:
2022     * <pre> {@code
2023     * class QueueTaker<E> implements ManagedBlocker {
2024     * final BlockingQueue<E> queue;
2025     * volatile E item = null;
2026     * QueueTaker(BlockingQueue<E> q) { this.queue = q; }
2027     * public boolean block() throws InterruptedException {
2028     * if (item == null)
2029 dl 1.23 * item = queue.take();
2030 dl 1.19 * return true;
2031     * }
2032     * public boolean isReleasable() {
2033 dl 1.23 * return item != null || (item = queue.poll()) != null;
2034 dl 1.19 * }
2035     * public E getItem() { // call after pool.managedBlock completes
2036     * return item;
2037     * }
2038     * }}</pre>
2039 jsr166 1.1 */
2040     public static interface ManagedBlocker {
2041     /**
2042     * Possibly blocks the current thread, for example waiting for
2043     * a lock or condition.
2044     *
2045 jsr166 1.4 * @return {@code true} if no additional blocking is necessary
2046     * (i.e., if isReleasable would return true)
2047 jsr166 1.1 * @throws InterruptedException if interrupted while waiting
2048     * (the method is not required to do so, but is allowed to)
2049     */
2050     boolean block() throws InterruptedException;
2051    
2052     /**
2053 jsr166 1.4 * Returns {@code true} if blocking is unnecessary.
2054 jsr166 1.1 */
2055     boolean isReleasable();
2056     }
2057    
2058     /**
2059     * Blocks in accord with the given blocker. If the current thread
2060 jsr166 1.8 * is a {@link ForkJoinWorkerThread}, this method possibly
2061     * arranges for a spare thread to be activated if necessary to
2062 dl 1.18 * ensure sufficient parallelism while the current thread is blocked.
2063 jsr166 1.1 *
2064 jsr166 1.8 * <p>If the caller is not a {@link ForkJoinTask}, this method is
2065     * behaviorally equivalent to
2066 jsr166 1.1 * <pre> {@code
2067     * while (!blocker.isReleasable())
2068     * if (blocker.block())
2069     * return;
2070     * }</pre>
2071 jsr166 1.8 *
2072     * If the caller is a {@code ForkJoinTask}, then the pool may
2073     * first be expanded to ensure parallelism, and later adjusted.
2074 jsr166 1.1 *
2075     * @param blocker the blocker
2076     * @throws InterruptedException if blocker.block did so
2077     */
2078 dl 1.18 public static void managedBlock(ManagedBlocker blocker)
2079 jsr166 1.1 throws InterruptedException {
2080     Thread t = Thread.currentThread();
2081 dl 1.19 if (t instanceof ForkJoinWorkerThread) {
2082     ForkJoinWorkerThread w = (ForkJoinWorkerThread) t;
2083     w.pool.awaitBlocker(blocker);
2084     }
2085 dl 1.18 else {
2086     do {} while (!blocker.isReleasable() && !blocker.block());
2087     }
2088 jsr166 1.1 }
2089    
2090 jsr166 1.7 // AbstractExecutorService overrides. These rely on undocumented
2091     // fact that ForkJoinTask.adapt returns ForkJoinTasks that also
2092     // implement RunnableFuture.
2093 jsr166 1.1
2094     protected <T> RunnableFuture<T> newTaskFor(Runnable runnable, T value) {
2095 jsr166 1.7 return (RunnableFuture<T>) ForkJoinTask.adapt(runnable, value);
2096 jsr166 1.1 }
2097    
2098     protected <T> RunnableFuture<T> newTaskFor(Callable<T> callable) {
2099 jsr166 1.7 return (RunnableFuture<T>) ForkJoinTask.adapt(callable);
2100 jsr166 1.1 }
2101    
2102     // Unsafe mechanics
2103 dl 1.52 private static final sun.misc.Unsafe UNSAFE;
2104     private static final long ctlOffset;
2105     private static final long stealCountOffset;
2106     private static final long blockedCountOffset;
2107     private static final long quiescerCountOffset;
2108     private static final long scanGuardOffset;
2109     private static final long nextWorkerNumberOffset;
2110     private static final long ABASE;
2111     private static final int ASHIFT;
2112    
2113     static {
2114     poolNumberGenerator = new AtomicInteger();
2115     workerSeedGenerator = new Random();
2116     modifyThreadPermission = new RuntimePermission("modifyThread");
2117     defaultForkJoinWorkerThreadFactory =
2118     new DefaultForkJoinWorkerThreadFactory();
2119     int s;
2120 jsr166 1.3 try {
2121 dl 1.52 UNSAFE = sun.misc.Unsafe.getUnsafe();
2122 jsr166 1.64 Class<?> k = ForkJoinPool.class;
2123 dl 1.52 ctlOffset = UNSAFE.objectFieldOffset
2124     (k.getDeclaredField("ctl"));
2125     stealCountOffset = UNSAFE.objectFieldOffset
2126     (k.getDeclaredField("stealCount"));
2127     blockedCountOffset = UNSAFE.objectFieldOffset
2128     (k.getDeclaredField("blockedCount"));
2129     quiescerCountOffset = UNSAFE.objectFieldOffset
2130     (k.getDeclaredField("quiescerCount"));
2131     scanGuardOffset = UNSAFE.objectFieldOffset
2132     (k.getDeclaredField("scanGuard"));
2133     nextWorkerNumberOffset = UNSAFE.objectFieldOffset
2134     (k.getDeclaredField("nextWorkerNumber"));
2135 jsr166 1.64 Class<?> a = ForkJoinTask[].class;
2136 dl 1.52 ABASE = UNSAFE.arrayBaseOffset(a);
2137     s = UNSAFE.arrayIndexScale(a);
2138     } catch (Exception e) {
2139     throw new Error(e);
2140     }
2141     if ((s & (s-1)) != 0)
2142     throw new Error("data type scale not a power of two");
2143     ASHIFT = 31 - Integer.numberOfLeadingZeros(s);
2144 jsr166 1.3 }
2145 dl 1.52
2146 jsr166 1.1 }