ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jdk8/java/util/concurrent/package-info.java
Revision: 1.3
Committed: Sun Sep 25 01:21:22 2016 UTC (7 years, 7 months ago) by jsr166
Branch: MAIN
CVS Tags: HEAD
Changes since 1.2: +1 -1 lines
Log Message: 
ConcurrentHashMap concurrency no longer tunable

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     * 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 jsr166 1.3 * concurrent reads as well as a large number of concurrent
175 jsr166 1.1 * 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&trade; 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;