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