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 |
|
|
* http://creativecommons.org/publicdomain/zero/1.0/ |
5 |
|
|
*/ |
6 |
|
|
|
7 |
|
|
/** |
8 |
|
|
* Utility classes commonly useful in concurrent programming. This |
9 |
|
|
* package includes a few small standardized extensible frameworks, as |
10 |
|
|
* well as some classes that provide useful functionality and are |
11 |
|
|
* otherwise tedious or difficult to implement. Here are brief |
12 |
|
|
* descriptions of the main components. See also the |
13 |
|
|
* {@link java.util.concurrent.locks} and |
14 |
|
|
* {@link java.util.concurrent.atomic} packages. |
15 |
|
|
* |
16 |
|
|
* <h2>Executors</h2> |
17 |
|
|
* |
18 |
|
|
* <b>Interfaces.</b> |
19 |
|
|
* |
20 |
|
|
* {@link java.util.concurrent.Executor} is a simple standardized |
21 |
|
|
* interface for defining custom thread-like subsystems, including |
22 |
|
|
* thread pools, asynchronous I/O, and lightweight task frameworks. |
23 |
|
|
* Depending on which concrete Executor class is being used, tasks may |
24 |
|
|
* execute in a newly created thread, an existing task-execution thread, |
25 |
|
|
* or the thread calling {@link java.util.concurrent.Executor#execute |
26 |
|
|
* execute}, and may execute sequentially or concurrently. |
27 |
|
|
* |
28 |
|
|
* {@link java.util.concurrent.ExecutorService} provides a more |
29 |
|
|
* complete asynchronous task execution framework. An |
30 |
|
|
* ExecutorService manages queuing and scheduling of tasks, |
31 |
|
|
* and allows controlled shutdown. |
32 |
|
|
* |
33 |
|
|
* The {@link java.util.concurrent.ScheduledExecutorService} |
34 |
|
|
* subinterface and associated interfaces add support for |
35 |
|
|
* delayed and periodic task execution. ExecutorServices |
36 |
|
|
* provide methods arranging asynchronous execution of any |
37 |
|
|
* function expressed as {@link java.util.concurrent.Callable}, |
38 |
|
|
* the result-bearing analog of {@link java.lang.Runnable}. |
39 |
|
|
* |
40 |
|
|
* A {@link java.util.concurrent.Future} returns the results of |
41 |
|
|
* a function, allows determination of whether execution has |
42 |
|
|
* completed, and provides a means to cancel execution. |
43 |
|
|
* |
44 |
|
|
* A {@link java.util.concurrent.RunnableFuture} is a {@code Future} |
45 |
|
|
* that possesses a {@code run} method that upon execution, |
46 |
|
|
* sets its results. |
47 |
|
|
* |
48 |
|
|
* <p> |
49 |
|
|
* |
50 |
|
|
* <b>Implementations.</b> |
51 |
|
|
* |
52 |
|
|
* Classes {@link java.util.concurrent.ThreadPoolExecutor} and |
53 |
|
|
* {@link java.util.concurrent.ScheduledThreadPoolExecutor} |
54 |
|
|
* provide tunable, flexible thread pools. |
55 |
|
|
* |
56 |
|
|
* The {@link java.util.concurrent.Executors} class provides |
57 |
|
|
* factory methods for the most common kinds and configurations |
58 |
|
|
* of Executors, as well as a few utility methods for using |
59 |
|
|
* them. Other utilities based on {@code Executors} include the |
60 |
|
|
* concrete class {@link java.util.concurrent.FutureTask} |
61 |
|
|
* providing a common extensible implementation of Futures, and |
62 |
|
|
* {@link java.util.concurrent.ExecutorCompletionService}, that |
63 |
|
|
* assists in coordinating the processing of groups of |
64 |
|
|
* asynchronous tasks. |
65 |
|
|
* |
66 |
|
|
* <p>Class {@link java.util.concurrent.ForkJoinPool} provides an |
67 |
|
|
* Executor primarily designed for processing instances of {@link |
68 |
|
|
* java.util.concurrent.ForkJoinTask} and its subclasses. These |
69 |
|
|
* classes employ a work-stealing scheduler that attains high |
70 |
|
|
* throughput for tasks conforming to restrictions that often hold in |
71 |
|
|
* computation-intensive parallel processing. |
72 |
|
|
* |
73 |
|
|
* <h2>Queues</h2> |
74 |
|
|
* |
75 |
|
|
* The {@link java.util.concurrent.ConcurrentLinkedQueue} class |
76 |
|
|
* supplies an efficient scalable thread-safe non-blocking FIFO queue. |
77 |
|
|
* The {@link java.util.concurrent.ConcurrentLinkedDeque} class is |
78 |
|
|
* similar, but additionally supports the {@link java.util.Deque} |
79 |
|
|
* interface. |
80 |
|
|
* |
81 |
|
|
* <p>Five implementations in {@code java.util.concurrent} support |
82 |
|
|
* the extended {@link java.util.concurrent.BlockingQueue} |
83 |
|
|
* interface, that defines blocking versions of put and take: |
84 |
|
|
* {@link java.util.concurrent.LinkedBlockingQueue}, |
85 |
|
|
* {@link java.util.concurrent.ArrayBlockingQueue}, |
86 |
|
|
* {@link java.util.concurrent.SynchronousQueue}, |
87 |
|
|
* {@link java.util.concurrent.PriorityBlockingQueue}, and |
88 |
|
|
* {@link java.util.concurrent.DelayQueue}. |
89 |
|
|
* The different classes cover the most common usage contexts |
90 |
|
|
* for producer-consumer, messaging, parallel tasking, and |
91 |
|
|
* related concurrent designs. |
92 |
|
|
* |
93 |
|
|
* <p>Extended interface {@link java.util.concurrent.TransferQueue}, |
94 |
|
|
* and implementation {@link java.util.concurrent.LinkedTransferQueue} |
95 |
|
|
* introduce a synchronous {@code transfer} method (along with related |
96 |
|
|
* features) in which a producer may optionally block awaiting its |
97 |
|
|
* consumer. |
98 |
|
|
* |
99 |
|
|
* <p>The {@link java.util.concurrent.BlockingDeque} interface |
100 |
|
|
* extends {@code BlockingQueue} to support both FIFO and LIFO |
101 |
|
|
* (stack-based) operations. |
102 |
|
|
* Class {@link java.util.concurrent.LinkedBlockingDeque} |
103 |
|
|
* provides an implementation. |
104 |
|
|
* |
105 |
|
|
* <h2>Timing</h2> |
106 |
|
|
* |
107 |
|
|
* The {@link java.util.concurrent.TimeUnit} class provides |
108 |
|
|
* multiple granularities (including nanoseconds) for |
109 |
|
|
* specifying and controlling time-out based operations. Most |
110 |
|
|
* classes in the package contain operations based on time-outs |
111 |
|
|
* in addition to indefinite waits. In all cases that |
112 |
|
|
* time-outs are used, the time-out specifies the minimum time |
113 |
|
|
* that the method should wait before indicating that it |
114 |
|
|
* timed-out. Implementations make a "best effort" |
115 |
|
|
* to detect time-outs as soon as possible after they occur. |
116 |
|
|
* However, an indefinite amount of time may elapse between a |
117 |
|
|
* time-out being detected and a thread actually executing |
118 |
|
|
* again after that time-out. All methods that accept timeout |
119 |
|
|
* parameters treat values less than or equal to zero to mean |
120 |
|
|
* not to wait at all. To wait "forever", you can use a value |
121 |
|
|
* of {@code Long.MAX_VALUE}. |
122 |
|
|
* |
123 |
|
|
* <h2>Synchronizers</h2> |
124 |
|
|
* |
125 |
|
|
* Five classes aid common special-purpose synchronization idioms. |
126 |
|
|
* <ul> |
127 |
|
|
* |
128 |
|
|
* <li>{@link java.util.concurrent.Semaphore} is a classic concurrency tool. |
129 |
|
|
* |
130 |
|
|
* <li>{@link java.util.concurrent.CountDownLatch} is a very simple yet |
131 |
|
|
* very common utility for blocking until a given number of signals, |
132 |
|
|
* events, or conditions hold. |
133 |
|
|
* |
134 |
|
|
* <li>A {@link java.util.concurrent.CyclicBarrier} is a resettable |
135 |
|
|
* multiway synchronization point useful in some styles of parallel |
136 |
|
|
* programming. |
137 |
|
|
* |
138 |
|
|
* <li>A {@link java.util.concurrent.Phaser} provides |
139 |
|
|
* a more flexible form of barrier that may be used to control phased |
140 |
|
|
* computation among multiple threads. |
141 |
|
|
* |
142 |
|
|
* <li>An {@link java.util.concurrent.Exchanger} allows two threads to |
143 |
|
|
* exchange objects at a rendezvous point, and is useful in several |
144 |
|
|
* pipeline designs. |
145 |
|
|
* |
146 |
|
|
* </ul> |
147 |
|
|
* |
148 |
|
|
* <h2>Concurrent Collections</h2> |
149 |
|
|
* |
150 |
|
|
* Besides Queues, this package supplies Collection implementations |
151 |
|
|
* designed for use in multithreaded contexts: |
152 |
|
|
* {@link java.util.concurrent.ConcurrentHashMap}, |
153 |
|
|
* {@link java.util.concurrent.ConcurrentSkipListMap}, |
154 |
|
|
* {@link java.util.concurrent.ConcurrentSkipListSet}, |
155 |
|
|
* {@link java.util.concurrent.CopyOnWriteArrayList}, and |
156 |
|
|
* {@link java.util.concurrent.CopyOnWriteArraySet}. |
157 |
|
|
* When many threads are expected to access a given collection, a |
158 |
|
|
* {@code ConcurrentHashMap} is normally preferable to a synchronized |
159 |
|
|
* {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally |
160 |
|
|
* preferable to a synchronized {@code TreeMap}. |
161 |
|
|
* A {@code CopyOnWriteArrayList} is preferable to a synchronized |
162 |
|
|
* {@code ArrayList} when the expected number of reads and traversals |
163 |
|
|
* greatly outnumber the number of updates to a list. |
164 |
|
|
* |
165 |
|
|
* <p>The "Concurrent" prefix used with some classes in this package |
166 |
|
|
* is a shorthand indicating several differences from similar |
167 |
|
|
* "synchronized" classes. For example {@code java.util.Hashtable} and |
168 |
|
|
* {@code Collections.synchronizedMap(new HashMap())} are |
169 |
|
|
* synchronized. But {@link |
170 |
|
|
* java.util.concurrent.ConcurrentHashMap} is "concurrent". A |
171 |
|
|
* concurrent collection is thread-safe, but not governed by a |
172 |
|
|
* single exclusion lock. In the particular case of |
173 |
|
|
* ConcurrentHashMap, it safely permits any number of |
174 |
|
|
* concurrent reads as well as a tunable number of concurrent |
175 |
|
|
* writes. "Synchronized" classes can be useful when you need |
176 |
|
|
* to prevent all access to a collection via a single lock, at |
177 |
|
|
* the expense of poorer scalability. In other cases in which |
178 |
|
|
* multiple threads are expected to access a common collection, |
179 |
|
|
* "concurrent" versions are normally preferable. And |
180 |
|
|
* unsynchronized collections are preferable when either |
181 |
|
|
* collections are unshared, or are accessible only when |
182 |
|
|
* holding other locks. |
183 |
|
|
* |
184 |
|
|
* <p id="Weakly">Most concurrent Collection implementations |
185 |
|
|
* (including most Queues) also differ from the usual {@code java.util} |
186 |
|
|
* conventions in that their {@linkplain java.util.Iterator Iterators} |
187 |
|
|
* and {@linkplain java.util.Spliterator Spliterators} provide |
188 |
|
|
* <em>weakly consistent</em> rather than fast-fail traversal: |
189 |
|
|
* <ul> |
190 |
|
|
* <li>they may proceed concurrently with other operations |
191 |
|
|
* <li>they will never throw {@link java.util.ConcurrentModificationException |
192 |
|
|
* ConcurrentModificationException} |
193 |
|
|
* <li>they are guaranteed to traverse elements as they existed upon |
194 |
|
|
* construction exactly once, and may (but are not guaranteed to) |
195 |
|
|
* reflect any modifications subsequent to construction. |
196 |
|
|
* </ul> |
197 |
|
|
* |
198 |
|
|
* <h2 id="MemoryVisibility">Memory Consistency Properties</h2> |
199 |
|
|
* |
200 |
|
|
* <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.4.5"> |
201 |
|
|
* Chapter 17 of |
202 |
|
|
* <cite>The Java™ Language Specification</cite></a> defines the |
203 |
|
|
* <i>happens-before</i> relation on memory operations such as reads and |
204 |
|
|
* writes of shared variables. The results of a write by one thread are |
205 |
|
|
* guaranteed to be visible to a read by another thread only if the write |
206 |
|
|
* operation <i>happens-before</i> the read operation. The |
207 |
|
|
* {@code synchronized} and {@code volatile} constructs, as well as the |
208 |
|
|
* {@code Thread.start()} and {@code Thread.join()} methods, can form |
209 |
|
|
* <i>happens-before</i> relationships. In particular: |
210 |
|
|
* |
211 |
|
|
* <ul> |
212 |
|
|
* <li>Each action in a thread <i>happens-before</i> every action in that |
213 |
|
|
* thread that comes later in the program's order. |
214 |
|
|
* |
215 |
|
|
* <li>An unlock ({@code synchronized} block or method exit) of a |
216 |
|
|
* monitor <i>happens-before</i> every subsequent lock ({@code synchronized} |
217 |
|
|
* block or method entry) of that same monitor. And because |
218 |
|
|
* the <i>happens-before</i> relation is transitive, all actions |
219 |
|
|
* of a thread prior to unlocking <i>happen-before</i> all actions |
220 |
|
|
* subsequent to any thread locking that monitor. |
221 |
|
|
* |
222 |
|
|
* <li>A write to a {@code volatile} field <i>happens-before</i> every |
223 |
|
|
* subsequent read of that same field. Writes and reads of |
224 |
|
|
* {@code volatile} fields have similar memory consistency effects |
225 |
|
|
* as entering and exiting monitors, but do <em>not</em> entail |
226 |
|
|
* mutual exclusion locking. |
227 |
|
|
* |
228 |
|
|
* <li>A call to {@code start} on a thread <i>happens-before</i> any |
229 |
|
|
* action in the started thread. |
230 |
|
|
* |
231 |
|
|
* <li>All actions in a thread <i>happen-before</i> any other thread |
232 |
|
|
* successfully returns from a {@code join} on that thread. |
233 |
|
|
* |
234 |
|
|
* </ul> |
235 |
|
|
* |
236 |
|
|
* The methods of all classes in {@code java.util.concurrent} and its |
237 |
|
|
* subpackages extend these guarantees to higher-level |
238 |
|
|
* synchronization. In particular: |
239 |
|
|
* |
240 |
|
|
* <ul> |
241 |
|
|
* |
242 |
|
|
* <li>Actions in a thread prior to placing an object into any concurrent |
243 |
|
|
* collection <i>happen-before</i> actions subsequent to the access or |
244 |
|
|
* removal of that element from the collection in another thread. |
245 |
|
|
* |
246 |
|
|
* <li>Actions in a thread prior to the submission of a {@code Runnable} |
247 |
|
|
* to an {@code Executor} <i>happen-before</i> its execution begins. |
248 |
|
|
* Similarly for {@code Callables} submitted to an {@code ExecutorService}. |
249 |
|
|
* |
250 |
|
|
* <li>Actions taken by the asynchronous computation represented by a |
251 |
|
|
* {@code Future} <i>happen-before</i> actions subsequent to the |
252 |
|
|
* retrieval of the result via {@code Future.get()} in another thread. |
253 |
|
|
* |
254 |
|
|
* <li>Actions prior to "releasing" synchronizer methods such as |
255 |
|
|
* {@code Lock.unlock}, {@code Semaphore.release}, and |
256 |
|
|
* {@code CountDownLatch.countDown} <i>happen-before</i> actions |
257 |
|
|
* subsequent to a successful "acquiring" method such as |
258 |
|
|
* {@code Lock.lock}, {@code Semaphore.acquire}, |
259 |
|
|
* {@code Condition.await}, and {@code CountDownLatch.await} on the |
260 |
|
|
* same synchronizer object in another thread. |
261 |
|
|
* |
262 |
|
|
* <li>For each pair of threads that successfully exchange objects via |
263 |
|
|
* an {@code Exchanger}, actions prior to the {@code exchange()} |
264 |
|
|
* in each thread <i>happen-before</i> those subsequent to the |
265 |
|
|
* corresponding {@code exchange()} in another thread. |
266 |
|
|
* |
267 |
|
|
* <li>Actions prior to calling {@code CyclicBarrier.await} and |
268 |
|
|
* {@code Phaser.awaitAdvance} (as well as its variants) |
269 |
|
|
* <i>happen-before</i> actions performed by the barrier action, and |
270 |
|
|
* actions performed by the barrier action <i>happen-before</i> actions |
271 |
|
|
* subsequent to a successful return from the corresponding {@code await} |
272 |
|
|
* in other threads. |
273 |
|
|
* |
274 |
|
|
* </ul> |
275 |
|
|
* |
276 |
|
|
* @since 1.5 |
277 |
|
|
*/ |
278 |
|
|
package java.util.concurrent; |