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