util/concurrent/package-info.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/licenses/publicdomain
 */

/**
 * Utility classes commonly useful in concurrent programming.  This
 * package includes a few small standardized extensible frameworks, as
 * well as some classes that provide useful functionality and are
 * otherwise tedious or difficult to implement.  Here are brief
 * descriptions of the main components.  See also the
 * {@link java.util.concurrent.locks} and
 * {@link java.util.concurrent.atomic} packages.
 *
 * <h2>Executors</h2>
 *
 * <b>Interfaces.</b>
 *
 * {@link java.util.concurrent.Executor} is a simple standardized
 * interface for defining custom thread-like subsystems, including
 * thread pools, asynchronous IO, and lightweight task frameworks.
 * Depending on which concrete Executor class is being used, tasks may
 * execute in a newly created thread, an existing task-execution thread,
 * or the thread calling {@link java.util.concurrent.Executor#execute
 * execute}, and may execute sequentially or concurrently.
 *
 * {@link java.util.concurrent.ExecutorService} provides a more
 * complete asynchronous task execution framework.  An
 * ExecutorService manages queuing and scheduling of tasks,
 * and allows controlled shutdown.
 *
 * The {@link java.util.concurrent.ScheduledExecutorService}
 * subinterface and associated interfaces add support for
 * delayed and periodic task execution.  ExecutorServices
 * provide methods arranging asynchronous execution of any
 * function expressed as {@link java.util.concurrent.Callable},
 * the result-bearing analog of {@link java.lang.Runnable}.
 *
 * A {@link java.util.concurrent.Future} returns the results of
 * a function, allows determination of whether execution has
 * completed, and provides a means to cancel execution.
 *
 * A {@link java.util.concurrent.RunnableFuture} is a {@code Future}
 * that possesses a {@code run} method that upon execution,
 * sets its results.
 *
 * <p>
 *
 * <b>Implementations.</b>
 *
 * Classes {@link java.util.concurrent.ThreadPoolExecutor} and
 * {@link java.util.concurrent.ScheduledThreadPoolExecutor}
 * provide tunable, flexible thread pools.
 *
 * The {@link java.util.concurrent.Executors} class provides
 * factory methods for the most common kinds and configurations
 * of Executors, as well as a few utility methods for using
 * them.  Other utilities based on {@code Executors} include the
 * concrete class {@link java.util.concurrent.FutureTask}
 * providing a common extensible implementation of Futures, and
 * {@link java.util.concurrent.ExecutorCompletionService}, that
 * assists in coordinating the processing of groups of
 * asynchronous tasks.
 *
 * <h2>Queues</h2>
 *
 * The {@link java.util.concurrent.ConcurrentLinkedQueue} class
 * supplies an efficient scalable thread-safe non-blocking FIFO
 * queue.
 *
 * <p>Five implementations in {@code java.util.concurrent} support
 * the extended {@link java.util.concurrent.BlockingQueue}
 * interface, that defines blocking versions of put and take:
 * {@link java.util.concurrent.LinkedBlockingQueue},
 * {@link java.util.concurrent.ArrayBlockingQueue},
 * {@link java.util.concurrent.SynchronousQueue},
 * {@link java.util.concurrent.PriorityBlockingQueue}, and
 * {@link java.util.concurrent.DelayQueue}.
 * The different classes cover the most common usage contexts
 * for producer-consumer, messaging, parallel tasking, and
 * related concurrent designs.
 *
 * <p>The {@link java.util.concurrent.BlockingDeque} interface
 * extends {@code BlockingQueue} to support both FIFO and LIFO
 * (stack-based) operations.
 * Class {@link java.util.concurrent.LinkedBlockingDeque}
 * provides an implementation.
 *
 * <h2>Timing</h2>
 *
 * The {@link java.util.concurrent.TimeUnit} class provides
 * multiple granularities (including nanoseconds) for
 * specifying and controlling time-out based operations.  Most
 * classes in the package contain operations based on time-outs
 * in addition to indefinite waits.  In all cases that
 * time-outs are used, the time-out specifies the minimum time
 * that the method should wait before indicating that it
 * timed-out.  Implementations make a &quot;best effort&quot;
 * to detect time-outs as soon as possible after they occur.
 * However, an indefinite amount of time may elapse between a
 * time-out being detected and a thread actually executing
 * again after that time-out.  All methods that accept timeout
 * parameters treat values less than or equal to zero to mean
 * not to wait at all.  To wait "forever", you can use a value
 * of {@code Long.MAX_VALUE}.
 *
 * <h2>Synchronizers</h2>
 *
 * Four classes aid common special-purpose synchronization idioms.
 * {@link java.util.concurrent.Semaphore} is a classic concurrency tool.
 * {@link java.util.concurrent.CountDownLatch} is a very simple yet very
 * common utility for blocking until a given number of signals, events,
 * or conditions hold.  A {@link java.util.concurrent.CyclicBarrier} is a
 * resettable multiway synchronization point useful in some styles of
 * parallel programming.  An {@link java.util.concurrent.Exchanger} allows
 * two threads to exchange objects at a rendezvous point, and is useful
 * in several pipeline designs.
 *
 * <h2>Concurrent Collections</h2>
 *
 * Besides Queues, this package supplies Collection implementations
 * designed for use in multithreaded contexts:
 * {@link java.util.concurrent.ConcurrentHashMap},
 * {@link java.util.concurrent.ConcurrentSkipListMap},
 * {@link java.util.concurrent.ConcurrentSkipListSet},
 * {@link java.util.concurrent.CopyOnWriteArrayList}, and
 * {@link java.util.concurrent.CopyOnWriteArraySet}.
 * When many threads are expected to access a given collection, a
 * {@code ConcurrentHashMap} is normally preferable to a synchronized
 * {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally
 * preferable to a synchronized {@code TreeMap}.
 * A {@code CopyOnWriteArrayList} is preferable to a synchronized
 * {@code ArrayList} when the expected number of reads and traversals
 * greatly outnumber the number of updates to a list.

 * <p>The "Concurrent" prefix used with some classes in this package
 * is a shorthand indicating several differences from similar
 * "synchronized" classes.  For example {@code java.util.Hashtable} and
 * {@code Collections.synchronizedMap(new HashMap())} are
 * synchronized.  But {@link
 * java.util.concurrent.ConcurrentHashMap} is "concurrent".  A
 * concurrent collection is thread-safe, but not governed by a
 * single exclusion lock.  In the particular case of
 * ConcurrentHashMap, it safely permits any number of
 * concurrent reads as well as a tunable number of concurrent
 * writes.  "Synchronized" classes can be useful when you need
 * to prevent all access to a collection via a single lock, at
 * the expense of poorer scalability.  In other cases in which
 * multiple threads are expected to access a common collection,
 * "concurrent" versions are normally preferable.  And
 * unsynchronized collections are preferable when either
 * collections are unshared, or are accessible only when
 * holding other locks.
 *
 * <p>Most concurrent Collection implementations (including most
 * Queues) also differ from the usual java.util conventions in that
 * their Iterators provide <em>weakly consistent</em> rather than
 * fast-fail traversal.  A weakly consistent iterator is thread-safe,
 * but does not necessarily freeze the collection while iterating, so
 * it may (or may not) reflect any updates since the iterator was
 * created.
 *
 * <h2><a name="MemoryVisibility">Memory Consistency Properties</a></h2>
 *
 * <a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html">
 * Chapter 17 of the Java Language Specification</a> defines the
 * <i>happens-before</i> relation on memory operations such as reads and
 * writes of shared variables.  The results of a write by one thread are
 * guaranteed to be visible to a read by another thread only if the write
 * operation <i>happens-before</i> the read operation.  The
 * {@code synchronized} and {@code volatile} constructs, as well as the
 * {@code Thread.start()} and {@code Thread.join()} methods, can form
 * <i>happens-before</i> relationships.  In particular:
 *
 * <ul>
 *   <li>Each action in a thread <i>happens-before</i> every action in that
 *   thread that comes later in the program's order.
 *
 *   <li>An unlock ({@code synchronized} block or method exit) of a
 *   monitor <i>happens-before</i> every subsequent lock ({@code synchronized}
 *   block or method entry) of that same monitor.  And because
 *   the <i>happens-before</i> relation is transitive, all actions
 *   of a thread prior to unlocking <i>happen-before</i> all actions
 *   subsequent to any thread locking that monitor.
 *
 *   <li>A write to a {@code volatile} field <i>happens-before</i> every
 *   subsequent read of that same field.  Writes and reads of
 *   {@code volatile} fields have similar memory consistency effects
 *   as entering and exiting monitors, but do <em>not</em> entail
 *   mutual exclusion locking.
 *
 *   <li>A call to {@code start} on a thread <i>happens-before</i> any
 *   action in the started thread.
 *
 *   <li>All actions in a thread <i>happen-before</i> any other thread
 *   successfully returns from a {@code join} on that thread.
 *
 * </ul>
 *
 *
 * The methods of all classes in {@code java.util.concurrent} and its
 * subpackages extend these guarantees to higher-level
 * synchronization.  In particular:
 *
 * <ul>
 *
 *   <li>Actions in a thread prior to placing an object into any concurrent
 *   collection <i>happen-before</i> actions subsequent to the access or
 *   removal of that element from the collection in another thread.
 *
 *   <li>Actions in a thread prior to the submission of a {@code Runnable}
 *   to an {@code Executor} <i>happen-before</i> its execution begins.
 *   Similarly for {@code Callables} submitted to an {@code ExecutorService}.
 *
 *   <li>Actions taken by the asynchronous computation represented by a
 *   {@code Future} <i>happen-before</i> actions subsequent to the
 *   retrieval of the result via {@code Future.get()} in another thread.
 *
 *   <li>Actions prior to "releasing" synchronizer methods such as
 *   {@code Lock.unlock}, {@code Semaphore.release}, and
 *   {@code CountDownLatch.countDown} <i>happen-before</i> actions
 *   subsequent to a successful "acquiring" method such as
 *   {@code Lock.lock}, {@code Semaphore.acquire},
 *   {@code Condition.await}, and {@code CountDownLatch.await} on the
 *   same synchronizer object in another thread.
 *
 *   <li>For each pair of threads that successfully exchange objects via
 *   an {@code Exchanger}, actions prior to the {@code exchange()}
 *   in each thread <i>happen-before</i> those subsequent to the
 *   corresponding {@code exchange()} in another thread.
 *
 *   <li>Actions prior to calling {@code CyclicBarrier.await}
 *   <i>happen-before</i> actions performed by the barrier action, and
 *   actions performed by the barrier action <i>happen-before</i> actions
 *   subsequent to a successful return from the corresponding {@code await}
 *   in other threads.
 *
 * </ul>
 *
 * @since 1.5
 */
package java.util.concurrent;
Revision:	1.1
Committed:	Sun May 20 08:45:03 2007 UTC (17 years ago) by jsr166
Branch:	MAIN
Log Message:	6558708: Rewrite package.html as package-info.java
#	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/licenses/publicdomain
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 IO, 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			* <h2>Queues</h2>
67			*
68			* The {@link java.util.concurrent.ConcurrentLinkedQueue} class
69			* supplies an efficient scalable thread-safe non-blocking FIFO
70			* queue.
71			*
72			* <p>Five implementations in {@code java.util.concurrent} support
73			* the extended {@link java.util.concurrent.BlockingQueue}
74			* interface, that defines blocking versions of put and take:
75			* {@link java.util.concurrent.LinkedBlockingQueue},
76			* {@link java.util.concurrent.ArrayBlockingQueue},
77			* {@link java.util.concurrent.SynchronousQueue},
78			* {@link java.util.concurrent.PriorityBlockingQueue}, and
79			* {@link java.util.concurrent.DelayQueue}.
80			* The different classes cover the most common usage contexts
81			* for producer-consumer, messaging, parallel tasking, and
82			* related concurrent designs.
83			*
84			* <p>The {@link java.util.concurrent.BlockingDeque} interface
85			* extends {@code BlockingQueue} to support both FIFO and LIFO
86			* (stack-based) operations.
87			* Class {@link java.util.concurrent.LinkedBlockingDeque}
88			* provides an implementation.
89			*
90			* <h2>Timing</h2>
91			*
92			* The {@link java.util.concurrent.TimeUnit} class provides
93			* multiple granularities (including nanoseconds) for
94			* specifying and controlling time-out based operations. Most
95			* classes in the package contain operations based on time-outs
96			* in addition to indefinite waits. In all cases that
97			* time-outs are used, the time-out specifies the minimum time
98			* that the method should wait before indicating that it
99			* timed-out. Implementations make a "best effort"
100			* to detect time-outs as soon as possible after they occur.
101			* However, an indefinite amount of time may elapse between a
102			* time-out being detected and a thread actually executing
103			* again after that time-out. All methods that accept timeout
104			* parameters treat values less than or equal to zero to mean
105			* not to wait at all. To wait "forever", you can use a value
106			* of {@code Long.MAX_VALUE}.
107			*
108			* <h2>Synchronizers</h2>
109			*
110			* Four classes aid common special-purpose synchronization idioms.
111			* {@link java.util.concurrent.Semaphore} is a classic concurrency tool.
112			* {@link java.util.concurrent.CountDownLatch} is a very simple yet very
113			* common utility for blocking until a given number of signals, events,
114			* or conditions hold. A {@link java.util.concurrent.CyclicBarrier} is a
115			* resettable multiway synchronization point useful in some styles of
116			* parallel programming. An {@link java.util.concurrent.Exchanger} allows
117			* two threads to exchange objects at a rendezvous point, and is useful
118			* in several pipeline designs.
119			*
120			* <h2>Concurrent Collections</h2>
121			*
122			* Besides Queues, this package supplies Collection implementations
123			* designed for use in multithreaded contexts:
124			* {@link java.util.concurrent.ConcurrentHashMap},
125			* {@link java.util.concurrent.ConcurrentSkipListMap},
126			* {@link java.util.concurrent.ConcurrentSkipListSet},
127			* {@link java.util.concurrent.CopyOnWriteArrayList}, and
128			* {@link java.util.concurrent.CopyOnWriteArraySet}.
129			* When many threads are expected to access a given collection, a
130			* {@code ConcurrentHashMap} is normally preferable to a synchronized
131			* {@code HashMap}, and a {@code ConcurrentSkipListMap} is normally
132			* preferable to a synchronized {@code TreeMap}.
133			* A {@code CopyOnWriteArrayList} is preferable to a synchronized
134			* {@code ArrayList} when the expected number of reads and traversals
135			* greatly outnumber the number of updates to a list.
136
137			* <p>The "Concurrent" prefix used with some classes in this package
138			* is a shorthand indicating several differences from similar
139			* "synchronized" classes. For example {@code java.util.Hashtable} and
140			* {@code Collections.synchronizedMap(new HashMap())} are
141			* synchronized. But {@link
142			* java.util.concurrent.ConcurrentHashMap} is "concurrent". A
143			* concurrent collection is thread-safe, but not governed by a
144			* single exclusion lock. In the particular case of
145			* ConcurrentHashMap, it safely permits any number of
146			* concurrent reads as well as a tunable number of concurrent
147			* writes. "Synchronized" classes can be useful when you need
148			* to prevent all access to a collection via a single lock, at
149			* the expense of poorer scalability. In other cases in which
150			* multiple threads are expected to access a common collection,
151			* "concurrent" versions are normally preferable. And
152			* unsynchronized collections are preferable when either
153			* collections are unshared, or are accessible only when
154			* holding other locks.
155			*
156			* <p>Most concurrent Collection implementations (including most
157			* Queues) also differ from the usual java.util conventions in that
158			* their Iterators provide <em>weakly consistent</em> rather than
159			* fast-fail traversal. A weakly consistent iterator is thread-safe,
160			* but does not necessarily freeze the collection while iterating, so
161			* it may (or may not) reflect any updates since the iterator was
162			* created.
163			*
164			* <h2><a name="MemoryVisibility">Memory Consistency Properties</a></h2>
165			*
166			* <a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html">
167			* Chapter 17 of the Java Language Specification</a> defines the
168			* <i>happens-before</i> relation on memory operations such as reads and
169			* writes of shared variables. The results of a write by one thread are
170			* guaranteed to be visible to a read by another thread only if the write
171			* operation <i>happens-before</i> the read operation. The
172			* {@code synchronized} and {@code volatile} constructs, as well as the
173			* {@code Thread.start()} and {@code Thread.join()} methods, can form
174			* <i>happens-before</i> relationships. In particular:
175			*
176			* <ul>
177			* <li>Each action in a thread <i>happens-before</i> every action in that
178			* thread that comes later in the program's order.
179			*
180			* <li>An unlock ({@code synchronized} block or method exit) of a
181			* monitor <i>happens-before</i> every subsequent lock ({@code synchronized}
182			* block or method entry) of that same monitor. And because
183			* the <i>happens-before</i> relation is transitive, all actions
184			* of a thread prior to unlocking <i>happen-before</i> all actions
185			* subsequent to any thread locking that monitor.
186			*
187			* <li>A write to a {@code volatile} field <i>happens-before</i> every
188			* subsequent read of that same field. Writes and reads of
189			* {@code volatile} fields have similar memory consistency effects
190			* as entering and exiting monitors, but do <em>not</em> entail
191			* mutual exclusion locking.
192			*
193			* <li>A call to {@code start} on a thread <i>happens-before</i> any
194			* action in the started thread.
195			*
196			* <li>All actions in a thread <i>happen-before</i> any other thread
197			* successfully returns from a {@code join} on that thread.
198			*
199			* </ul>
200			*
201			*
202			* The methods of all classes in {@code java.util.concurrent} and its
203			* subpackages extend these guarantees to higher-level
204			* synchronization. In particular:
205			*
206			* <ul>
207			*
208			* <li>Actions in a thread prior to placing an object into any concurrent
209			* collection <i>happen-before</i> actions subsequent to the access or
210			* removal of that element from the collection in another thread.
211			*
212			* <li>Actions in a thread prior to the submission of a {@code Runnable}
213			* to an {@code Executor} <i>happen-before</i> its execution begins.
214			* Similarly for {@code Callables} submitted to an {@code ExecutorService}.
215			*
216			* <li>Actions taken by the asynchronous computation represented by a
217			* {@code Future} <i>happen-before</i> actions subsequent to the
218			* retrieval of the result via {@code Future.get()} in another thread.
219			*
220			* <li>Actions prior to "releasing" synchronizer methods such as
221			* {@code Lock.unlock}, {@code Semaphore.release}, and
222			* {@code CountDownLatch.countDown} <i>happen-before</i> actions
223			* subsequent to a successful "acquiring" method such as
224			* {@code Lock.lock}, {@code Semaphore.acquire},
225			* {@code Condition.await}, and {@code CountDownLatch.await} on the
226			* same synchronizer object in another thread.
227			*
228			* <li>For each pair of threads that successfully exchange objects via
229			* an {@code Exchanger}, actions prior to the {@code exchange()}
230			* in each thread <i>happen-before</i> those subsequent to the
231			* corresponding {@code exchange()} in another thread.
232			*
233			* <li>Actions prior to calling {@code CyclicBarrier.await}
234			* <i>happen-before</i> actions performed by the barrier action, and
235			* actions performed by the barrier action <i>happen-before</i> actions
236			* subsequent to a successful return from the corresponding {@code await}
237			* in other threads.
238			*
239			* </ul>
240			*
241			* @since 1.5
242			*/
243			package java.util.concurrent;