ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jdk7/java/util/concurrent/package-info.java
Revision: 1.7
Committed: Fri Jul 15 18:49:12 2016 UTC (7 years, 10 months ago) by jsr166
Branch: MAIN
CVS Tags: HEAD
Changes since 1.6: +0 -1 lines
Log Message:
whitespace

File Contents

# Content
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 &quot;best effort&quot;
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>Most concurrent Collection implementations (including most
185 * Queues) also differ from the usual java.util conventions in that
186 * their Iterators provide <em>weakly consistent</em> rather than
187 * fast-fail traversal. A weakly consistent iterator is thread-safe,
188 * but does not necessarily freeze the collection while iterating, so
189 * it may (or may not) reflect any updates since the iterator was
190 * created.
191 *
192 * <h2 id="MemoryVisibility">Memory Consistency Properties</h2>
193 *
194 * <a href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4.5">
195 * Chapter 17 of the Java Language Specification</a> defines the
196 * <i>happens-before</i> relation on memory operations such as reads and
197 * writes of shared variables. The results of a write by one thread are
198 * guaranteed to be visible to a read by another thread only if the write
199 * operation <i>happens-before</i> the read operation. The
200 * {@code synchronized} and {@code volatile} constructs, as well as the
201 * {@code Thread.start()} and {@code Thread.join()} methods, can form
202 * <i>happens-before</i> relationships. In particular:
203 *
204 * <ul>
205 * <li>Each action in a thread <i>happens-before</i> every action in that
206 * thread that comes later in the program's order.
207 *
208 * <li>An unlock ({@code synchronized} block or method exit) of a
209 * monitor <i>happens-before</i> every subsequent lock ({@code synchronized}
210 * block or method entry) of that same monitor. And because
211 * the <i>happens-before</i> relation is transitive, all actions
212 * of a thread prior to unlocking <i>happen-before</i> all actions
213 * subsequent to any thread locking that monitor.
214 *
215 * <li>A write to a {@code volatile} field <i>happens-before</i> every
216 * subsequent read of that same field. Writes and reads of
217 * {@code volatile} fields have similar memory consistency effects
218 * as entering and exiting monitors, but do <em>not</em> entail
219 * mutual exclusion locking.
220 *
221 * <li>A call to {@code start} on a thread <i>happens-before</i> any
222 * action in the started thread.
223 *
224 * <li>All actions in a thread <i>happen-before</i> any other thread
225 * successfully returns from a {@code join} on that thread.
226 *
227 * </ul>
228 *
229 * The methods of all classes in {@code java.util.concurrent} and its
230 * subpackages extend these guarantees to higher-level
231 * synchronization. In particular:
232 *
233 * <ul>
234 *
235 * <li>Actions in a thread prior to placing an object into any concurrent
236 * collection <i>happen-before</i> actions subsequent to the access or
237 * removal of that element from the collection in another thread.
238 *
239 * <li>Actions in a thread prior to the submission of a {@code Runnable}
240 * to an {@code Executor} <i>happen-before</i> its execution begins.
241 * Similarly for {@code Callables} submitted to an {@code ExecutorService}.
242 *
243 * <li>Actions taken by the asynchronous computation represented by a
244 * {@code Future} <i>happen-before</i> actions subsequent to the
245 * retrieval of the result via {@code Future.get()} in another thread.
246 *
247 * <li>Actions prior to "releasing" synchronizer methods such as
248 * {@code Lock.unlock}, {@code Semaphore.release}, and
249 * {@code CountDownLatch.countDown} <i>happen-before</i> actions
250 * subsequent to a successful "acquiring" method such as
251 * {@code Lock.lock}, {@code Semaphore.acquire},
252 * {@code Condition.await}, and {@code CountDownLatch.await} on the
253 * same synchronizer object in another thread.
254 *
255 * <li>For each pair of threads that successfully exchange objects via
256 * an {@code Exchanger}, actions prior to the {@code exchange()}
257 * in each thread <i>happen-before</i> those subsequent to the
258 * corresponding {@code exchange()} in another thread.
259 *
260 * <li>Actions prior to calling {@code CyclicBarrier.await} and
261 * {@code Phaser.awaitAdvance} (as well as its variants)
262 * <i>happen-before</i> actions performed by the barrier action, and
263 * actions performed by the barrier action <i>happen-before</i> actions
264 * subsequent to a successful return from the corresponding {@code await}
265 * in other threads.
266 *
267 * </ul>
268 *
269 * @since 1.5
270 */
271 package java.util.concurrent;