[cvs] / jsr166 / src / main / java / util / concurrent / package.html Repository:
ViewVC logotype

Annotation of /jsr166/src/main/java/util/concurrent/package.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.23 - (view) (download) (as text)

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

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8