Print this page
Split |
Close |
Expand all |
Collapse all |
--- old/src/share/classes/java/util/concurrent/Exchanger.java
+++ new/src/share/classes/java/util/concurrent/Exchanger.java
1 1 /*
2 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3 3 *
4 4 * This code is free software; you can redistribute it and/or modify it
5 5 * under the terms of the GNU General Public License version 2 only, as
6 6 * published by the Free Software Foundation. Oracle designates this
7 7 * particular file as subject to the "Classpath" exception as provided
8 8 * by Oracle in the LICENSE file that accompanied this code.
9 9 *
10 10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 13 * version 2 for more details (a copy is included in the LICENSE file that
14 14 * accompanied this code).
15 15 *
16 16 * You should have received a copy of the GNU General Public License version
17 17 * 2 along with this work; if not, write to the Free Software Foundation,
18 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 19 *
20 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 21 * or visit www.oracle.com if you need additional information or have any
22 22 * questions.
23 23 */
24 24
25 25 /*
26 26 * This file is available under and governed by the GNU General Public
27 27 * License version 2 only, as published by the Free Software Foundation.
28 28 * However, the following notice accompanied the original version of this
29 29 * file:
30 30 *
31 31 * Written by Doug Lea, Bill Scherer, and Michael Scott with
32 32 * assistance from members of JCP JSR-166 Expert Group and released to
33 33 * the public domain, as explained at
34 34 * http://creativecommons.org/licenses/publicdomain
35 35 */
36 36
37 37 package java.util.concurrent;
38 38 import java.util.concurrent.atomic.*;
39 39 import java.util.concurrent.locks.LockSupport;
40 40
41 41 /**
42 42 * A synchronization point at which threads can pair and swap elements
43 43 * within pairs. Each thread presents some object on entry to the
44 44 * {@link #exchange exchange} method, matches with a partner thread,
45 45 * and receives its partner's object on return. An Exchanger may be
46 46 * viewed as a bidirectional form of a {@link SynchronousQueue}.
47 47 * Exchangers may be useful in applications such as genetic algorithms
48 48 * and pipeline designs.
49 49 *
50 50 * <p><b>Sample Usage:</b>
51 51 * Here are the highlights of a class that uses an {@code Exchanger}
52 52 * to swap buffers between threads so that the thread filling the
53 53 * buffer gets a freshly emptied one when it needs it, handing off the
54 54 * filled one to the thread emptying the buffer.
55 55 * <pre>{@code
56 56 * class FillAndEmpty {
57 57 * Exchanger<DataBuffer> exchanger = new Exchanger<DataBuffer>();
58 58 * DataBuffer initialEmptyBuffer = ... a made-up type
59 59 * DataBuffer initialFullBuffer = ...
60 60 *
61 61 * class FillingLoop implements Runnable {
62 62 * public void run() {
63 63 * DataBuffer currentBuffer = initialEmptyBuffer;
64 64 * try {
65 65 * while (currentBuffer != null) {
66 66 * addToBuffer(currentBuffer);
67 67 * if (currentBuffer.isFull())
68 68 * currentBuffer = exchanger.exchange(currentBuffer);
69 69 * }
70 70 * } catch (InterruptedException ex) { ... handle ... }
71 71 * }
72 72 * }
73 73 *
74 74 * class EmptyingLoop implements Runnable {
75 75 * public void run() {
76 76 * DataBuffer currentBuffer = initialFullBuffer;
77 77 * try {
78 78 * while (currentBuffer != null) {
79 79 * takeFromBuffer(currentBuffer);
80 80 * if (currentBuffer.isEmpty())
81 81 * currentBuffer = exchanger.exchange(currentBuffer);
82 82 * }
83 83 * } catch (InterruptedException ex) { ... handle ...}
84 84 * }
85 85 * }
86 86 *
87 87 * void start() {
88 88 * new Thread(new FillingLoop()).start();
89 89 * new Thread(new EmptyingLoop()).start();
90 90 * }
91 91 * }
92 92 * }</pre>
93 93 *
94 94 * <p>Memory consistency effects: For each pair of threads that
95 95 * successfully exchange objects via an {@code Exchanger}, actions
96 96 * prior to the {@code exchange()} in each thread
97 97 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
98 98 * those subsequent to a return from the corresponding {@code exchange()}
99 99 * in the other thread.
100 100 *
101 101 * @since 1.5
102 102 * @author Doug Lea and Bill Scherer and Michael Scott
103 103 * @param <V> The type of objects that may be exchanged
104 104 */
105 105 public class Exchanger<V> {
106 106 /*
107 107 * Algorithm Description:
108 108 *
109 109 * The basic idea is to maintain a "slot", which is a reference to
110 110 * a Node containing both an Item to offer and a "hole" waiting to
111 111 * get filled in. If an incoming "occupying" thread sees that the
112 112 * slot is null, it CAS'es (compareAndSets) a Node there and waits
113 113 * for another to invoke exchange. That second "fulfilling" thread
114 114 * sees that the slot is non-null, and so CASes it back to null,
115 115 * also exchanging items by CASing the hole, plus waking up the
116 116 * occupying thread if it is blocked. In each case CAS'es may
117 117 * fail because a slot at first appears non-null but is null upon
118 118 * CAS, or vice-versa. So threads may need to retry these
119 119 * actions.
120 120 *
121 121 * This simple approach works great when there are only a few
122 122 * threads using an Exchanger, but performance rapidly
123 123 * deteriorates due to CAS contention on the single slot when
124 124 * there are lots of threads using an exchanger. So instead we use
125 125 * an "arena"; basically a kind of hash table with a dynamically
126 126 * varying number of slots, any one of which can be used by
127 127 * threads performing an exchange. Incoming threads pick slots
128 128 * based on a hash of their Thread ids. If an incoming thread
129 129 * fails to CAS in its chosen slot, it picks an alternative slot
130 130 * instead. And similarly from there. If a thread successfully
131 131 * CASes into a slot but no other thread arrives, it tries
132 132 * another, heading toward the zero slot, which always exists even
133 133 * if the table shrinks. The particular mechanics controlling this
134 134 * are as follows:
135 135 *
136 136 * Waiting: Slot zero is special in that it is the only slot that
137 137 * exists when there is no contention. A thread occupying slot
138 138 * zero will block if no thread fulfills it after a short spin.
139 139 * In other cases, occupying threads eventually give up and try
140 140 * another slot. Waiting threads spin for a while (a period that
141 141 * should be a little less than a typical context-switch time)
142 142 * before either blocking (if slot zero) or giving up (if other
143 143 * slots) and restarting. There is no reason for threads to block
144 144 * unless there are unlikely to be any other threads present.
145 145 * Occupants are mainly avoiding memory contention so sit there
146 146 * quietly polling for a shorter period than it would take to
147 147 * block and then unblock them. Non-slot-zero waits that elapse
148 148 * because of lack of other threads waste around one extra
149 149 * context-switch time per try, which is still on average much
150 150 * faster than alternative approaches.
151 151 *
152 152 * Sizing: Usually, using only a few slots suffices to reduce
153 153 * contention. Especially with small numbers of threads, using
154 154 * too many slots can lead to just as poor performance as using
155 155 * too few of them, and there's not much room for error. The
156 156 * variable "max" maintains the number of slots actually in
157 157 * use. It is increased when a thread sees too many CAS
158 158 * failures. (This is analogous to resizing a regular hash table
159 159 * based on a target load factor, except here, growth steps are
160 160 * just one-by-one rather than proportional.) Growth requires
161 161 * contention failures in each of three tried slots. Requiring
162 162 * multiple failures for expansion copes with the fact that some
163 163 * failed CASes are not due to contention but instead to simple
164 164 * races between two threads or thread pre-emptions occurring
165 165 * between reading and CASing. Also, very transient peak
166 166 * contention can be much higher than the average sustainable
167 167 * levels. The max limit is decreased on average 50% of the times
168 168 * that a non-slot-zero wait elapses without being fulfilled.
169 169 * Threads experiencing elapsed waits move closer to zero, so
170 170 * eventually find existing (or future) threads even if the table
171 171 * has been shrunk due to inactivity. The chosen mechanics and
172 172 * thresholds for growing and shrinking are intrinsically
173 173 * entangled with indexing and hashing inside the exchange code,
174 174 * and can't be nicely abstracted out.
175 175 *
176 176 * Hashing: Each thread picks its initial slot to use in accord
177 177 * with a simple hashcode. The sequence is the same on each
178 178 * encounter by any given thread, but effectively random across
179 179 * threads. Using arenas encounters the classic cost vs quality
180 180 * tradeoffs of all hash tables. Here, we use a one-step FNV-1a
181 181 * hash code based on the current thread's Thread.getId(), along
182 182 * with a cheap approximation to a mod operation to select an
183 183 * index. The downside of optimizing index selection in this way
184 184 * is that the code is hardwired to use a maximum table size of
185 185 * 32. But this value more than suffices for known platforms and
186 186 * applications.
187 187 *
188 188 * Probing: On sensed contention of a selected slot, we probe
189 189 * sequentially through the table, analogously to linear probing
190 190 * after collision in a hash table. (We move circularly, in
191 191 * reverse order, to mesh best with table growth and shrinkage
192 192 * rules.) Except that to minimize the effects of false-alarms
193 193 * and cache thrashing, we try the first selected slot twice
194 194 * before moving.
195 195 *
196 196 * Padding: Even with contention management, slots are heavily
197 197 * contended, so use cache-padding to avoid poor memory
198 198 * performance. Because of this, slots are lazily constructed
199 199 * only when used, to avoid wasting this space unnecessarily.
200 200 * While isolation of locations is not much of an issue at first
201 201 * in an application, as time goes on and garbage-collectors
202 202 * perform compaction, slots are very likely to be moved adjacent
203 203 * to each other, which can cause much thrashing of cache lines on
204 204 * MPs unless padding is employed.
205 205 *
206 206 * This is an improvement of the algorithm described in the paper
207 207 * "A Scalable Elimination-based Exchange Channel" by William
208 208 * Scherer, Doug Lea, and Michael Scott in Proceedings of SCOOL05
209 209 * workshop. Available at: http://hdl.handle.net/1802/2104
210 210 */
211 211
212 212 /** The number of CPUs, for sizing and spin control */
213 213 private static final int NCPU = Runtime.getRuntime().availableProcessors();
214 214
215 215 /**
216 216 * The capacity of the arena. Set to a value that provides more
217 217 * than enough space to handle contention. On small machines
218 218 * most slots won't be used, but it is still not wasted because
219 219 * the extra space provides some machine-level address padding
220 220 * to minimize interference with heavily CAS'ed Slot locations.
221 221 * And on very large machines, performance eventually becomes
222 222 * bounded by memory bandwidth, not numbers of threads/CPUs.
223 223 * This constant cannot be changed without also modifying
224 224 * indexing and hashing algorithms.
225 225 */
226 226 private static final int CAPACITY = 32;
227 227
228 228 /**
229 229 * The value of "max" that will hold all threads without
230 230 * contention. When this value is less than CAPACITY, some
231 231 * otherwise wasted expansion can be avoided.
232 232 */
233 233 private static final int FULL =
234 234 Math.max(0, Math.min(CAPACITY, NCPU / 2) - 1);
235 235
236 236 /**
237 237 * The number of times to spin (doing nothing except polling a
238 238 * memory location) before blocking or giving up while waiting to
239 239 * be fulfilled. Should be zero on uniprocessors. On
240 240 * multiprocessors, this value should be large enough so that two
241 241 * threads exchanging items as fast as possible block only when
242 242 * one of them is stalled (due to GC or preemption), but not much
243 243 * longer, to avoid wasting CPU resources. Seen differently, this
244 244 * value is a little over half the number of cycles of an average
245 245 * context switch time on most systems. The value here is
246 246 * approximately the average of those across a range of tested
247 247 * systems.
248 248 */
249 249 private static final int SPINS = (NCPU == 1) ? 0 : 2000;
250 250
251 251 /**
252 252 * The number of times to spin before blocking in timed waits.
253 253 * Timed waits spin more slowly because checking the time takes
254 254 * time. The best value relies mainly on the relative rate of
255 255 * System.nanoTime vs memory accesses. The value is empirically
256 256 * derived to work well across a variety of systems.
257 257 */
258 258 private static final int TIMED_SPINS = SPINS / 20;
259 259
260 260 /**
261 261 * Sentinel item representing cancellation of a wait due to
262 262 * interruption, timeout, or elapsed spin-waits. This value is
263 263 * placed in holes on cancellation, and used as a return value
264 264 * from waiting methods to indicate failure to set or get hole.
265 265 */
266 266 private static final Object CANCEL = new Object();
267 267
268 268 /**
269 269 * Value representing null arguments/returns from public
270 270 * methods. This disambiguates from internal requirement that
271 271 * holes start out as null to mean they are not yet set.
272 272 */
273 273 private static final Object NULL_ITEM = new Object();
274 274
275 275 /**
276 276 * Nodes hold partially exchanged data. This class
277 277 * opportunistically subclasses AtomicReference to represent the
278 278 * hole. So get() returns hole, and compareAndSet CAS'es value
279 279 * into hole. This class cannot be parameterized as "V" because
280 280 * of the use of non-V CANCEL sentinels.
281 281 */
282 282 private static final class Node extends AtomicReference<Object> {
283 283 /** The element offered by the Thread creating this node. */
284 284 public final Object item;
285 285
286 286 /** The Thread waiting to be signalled; null until waiting. */
287 287 public volatile Thread waiter;
288 288
289 289 /**
290 290 * Creates node with given item and empty hole.
291 291 * @param item the item
292 292 */
293 293 public Node(Object item) {
294 294 this.item = item;
295 295 }
296 296 }
297 297
298 298 /**
299 299 * A Slot is an AtomicReference with heuristic padding to lessen
300 300 * cache effects of this heavily CAS'ed location. While the
301 301 * padding adds noticeable space, all slots are created only on
302 302 * demand, and there will be more than one of them only when it
303 303 * would improve throughput more than enough to outweigh using
304 304 * extra space.
305 305 */
306 306 private static final class Slot extends AtomicReference<Object> {
307 307 // Improve likelihood of isolation on <= 64 byte cache lines
308 308 long q0, q1, q2, q3, q4, q5, q6, q7, q8, q9, qa, qb, qc, qd, qe;
309 309 }
310 310
311 311 /**
312 312 * Slot array. Elements are lazily initialized when needed.
313 313 * Declared volatile to enable double-checked lazy construction.
314 314 */
315 315 private volatile Slot[] arena = new Slot[CAPACITY];
316 316
317 317 /**
318 318 * The maximum slot index being used. The value sometimes
319 319 * increases when a thread experiences too many CAS contentions,
320 320 * and sometimes decreases when a spin-wait elapses. Changes
321 321 * are performed only via compareAndSet, to avoid stale values
322 322 * when a thread happens to stall right before setting.
323 323 */
324 324 private final AtomicInteger max = new AtomicInteger();
325 325
326 326 /**
327 327 * Main exchange function, handling the different policy variants.
328 328 * Uses Object, not "V" as argument and return value to simplify
329 329 * handling of sentinel values. Callers from public methods decode
330 330 * and cast accordingly.
331 331 *
332 332 * @param item the (non-null) item to exchange
333 333 * @param timed true if the wait is timed
334 334 * @param nanos if timed, the maximum wait time
335 335 * @return the other thread's item, or CANCEL if interrupted or timed out
336 336 */
337 337 private Object doExchange(Object item, boolean timed, long nanos) {
338 338 Node me = new Node(item); // Create in case occupying
339 339 int index = hashIndex(); // Index of current slot
340 340 int fails = 0; // Number of CAS failures
341 341
342 342 for (;;) {
343 343 Object y; // Contents of current slot
344 344 Slot slot = arena[index];
345 345 if (slot == null) // Lazily initialize slots
346 346 createSlot(index); // Continue loop to reread
347 347 else if ((y = slot.get()) != null && // Try to fulfill
↓ open down ↓ |
347 lines elided |
↑ open up ↑ |
348 348 slot.compareAndSet(y, null)) {
349 349 Node you = (Node)y; // Transfer item
350 350 if (you.compareAndSet(null, item)) {
351 351 LockSupport.unpark(you.waiter);
352 352 return you.item;
353 353 } // Else cancelled; continue
354 354 }
355 355 else if (y == null && // Try to occupy
356 356 slot.compareAndSet(null, me)) {
357 357 if (index == 0) // Blocking wait for slot 0
358 - return timed? awaitNanos(me, slot, nanos): await(me, slot);
358 + return timed ?
359 + awaitNanos(me, slot, nanos) :
360 + await(me, slot);
359 361 Object v = spinWait(me, slot); // Spin wait for non-0
360 362 if (v != CANCEL)
361 363 return v;
362 364 me = new Node(item); // Throw away cancelled node
363 365 int m = max.get();
364 366 if (m > (index >>>= 1)) // Decrease index
365 367 max.compareAndSet(m, m - 1); // Maybe shrink table
366 368 }
367 369 else if (++fails > 1) { // Allow 2 fails on 1st slot
368 370 int m = max.get();
369 371 if (fails > 3 && m < FULL && max.compareAndSet(m, m + 1))
370 372 index = m + 1; // Grow on 3rd failed slot
371 373 else if (--index < 0)
372 374 index = m; // Circularly traverse
373 375 }
374 376 }
375 377 }
376 378
377 379 /**
378 380 * Returns a hash index for the current thread. Uses a one-step
379 381 * FNV-1a hash code (http://www.isthe.com/chongo/tech/comp/fnv/)
380 382 * based on the current thread's Thread.getId(). These hash codes
381 383 * have more uniform distribution properties with respect to small
382 384 * moduli (here 1-31) than do other simple hashing functions.
383 385 *
384 386 * <p>To return an index between 0 and max, we use a cheap
385 387 * approximation to a mod operation, that also corrects for bias
386 388 * due to non-power-of-2 remaindering (see {@link
387 389 * java.util.Random#nextInt}). Bits of the hashcode are masked
388 390 * with "nbits", the ceiling power of two of table size (looked up
389 391 * in a table packed into three ints). If too large, this is
390 392 * retried after rotating the hash by nbits bits, while forcing new
391 393 * top bit to 0, which guarantees eventual termination (although
392 394 * with a non-random-bias). This requires an average of less than
393 395 * 2 tries for all table sizes, and has a maximum 2% difference
394 396 * from perfectly uniform slot probabilities when applied to all
395 397 * possible hash codes for sizes less than 32.
396 398 *
397 399 * @return a per-thread-random index, 0 <= index < max
398 400 */
399 401 private final int hashIndex() {
400 402 long id = Thread.currentThread().getId();
401 403 int hash = (((int)(id ^ (id >>> 32))) ^ 0x811c9dc5) * 0x01000193;
402 404
403 405 int m = max.get();
404 406 int nbits = (((0xfffffc00 >> m) & 4) | // Compute ceil(log2(m+1))
405 407 ((0x000001f8 >>> m) & 2) | // The constants hold
406 408 ((0xffff00f2 >>> m) & 1)); // a lookup table
407 409 int index;
408 410 while ((index = hash & ((1 << nbits) - 1)) > m) // May retry on
409 411 hash = (hash >>> nbits) | (hash << (33 - nbits)); // non-power-2 m
410 412 return index;
411 413 }
412 414
413 415 /**
414 416 * Creates a new slot at given index. Called only when the slot
415 417 * appears to be null. Relies on double-check using builtin
416 418 * locks, since they rarely contend. This in turn relies on the
417 419 * arena array being declared volatile.
418 420 *
419 421 * @param index the index to add slot at
420 422 */
421 423 private void createSlot(int index) {
422 424 // Create slot outside of lock to narrow sync region
423 425 Slot newSlot = new Slot();
424 426 Slot[] a = arena;
425 427 synchronized (a) {
426 428 if (a[index] == null)
427 429 a[index] = newSlot;
428 430 }
429 431 }
430 432
431 433 /**
432 434 * Tries to cancel a wait for the given node waiting in the given
433 435 * slot, if so, helping clear the node from its slot to avoid
434 436 * garbage retention.
435 437 *
436 438 * @param node the waiting node
437 439 * @param the slot it is waiting in
438 440 * @return true if successfully cancelled
439 441 */
440 442 private static boolean tryCancel(Node node, Slot slot) {
441 443 if (!node.compareAndSet(null, CANCEL))
442 444 return false;
443 445 if (slot.get() == node) // pre-check to minimize contention
444 446 slot.compareAndSet(node, null);
445 447 return true;
446 448 }
447 449
448 450 // Three forms of waiting. Each just different enough not to merge
449 451 // code with others.
450 452
451 453 /**
452 454 * Spin-waits for hole for a non-0 slot. Fails if spin elapses
453 455 * before hole filled. Does not check interrupt, relying on check
454 456 * in public exchange method to abort if interrupted on entry.
455 457 *
456 458 * @param node the waiting node
457 459 * @return on success, the hole; on failure, CANCEL
458 460 */
459 461 private static Object spinWait(Node node, Slot slot) {
460 462 int spins = SPINS;
461 463 for (;;) {
462 464 Object v = node.get();
463 465 if (v != null)
464 466 return v;
465 467 else if (spins > 0)
466 468 --spins;
467 469 else
468 470 tryCancel(node, slot);
469 471 }
470 472 }
471 473
472 474 /**
473 475 * Waits for (by spinning and/or blocking) and gets the hole
474 476 * filled in by another thread. Fails if interrupted before
475 477 * hole filled.
476 478 *
477 479 * When a node/thread is about to block, it sets its waiter field
478 480 * and then rechecks state at least one more time before actually
479 481 * parking, thus covering race vs fulfiller noticing that waiter
480 482 * is non-null so should be woken.
481 483 *
482 484 * Thread interruption status is checked only surrounding calls to
483 485 * park. The caller is assumed to have checked interrupt status
484 486 * on entry.
485 487 *
486 488 * @param node the waiting node
487 489 * @return on success, the hole; on failure, CANCEL
488 490 */
489 491 private static Object await(Node node, Slot slot) {
490 492 Thread w = Thread.currentThread();
491 493 int spins = SPINS;
492 494 for (;;) {
493 495 Object v = node.get();
494 496 if (v != null)
495 497 return v;
496 498 else if (spins > 0) // Spin-wait phase
497 499 --spins;
498 500 else if (node.waiter == null) // Set up to block next
499 501 node.waiter = w;
500 502 else if (w.isInterrupted()) // Abort on interrupt
501 503 tryCancel(node, slot);
502 504 else // Block
503 505 LockSupport.park(node);
504 506 }
505 507 }
506 508
507 509 /**
508 510 * Waits for (at index 0) and gets the hole filled in by another
509 511 * thread. Fails if timed out or interrupted before hole filled.
510 512 * Same basic logic as untimed version, but a bit messier.
511 513 *
512 514 * @param node the waiting node
513 515 * @param nanos the wait time
514 516 * @return on success, the hole; on failure, CANCEL
515 517 */
516 518 private Object awaitNanos(Node node, Slot slot, long nanos) {
517 519 int spins = TIMED_SPINS;
518 520 long lastTime = 0;
519 521 Thread w = null;
520 522 for (;;) {
521 523 Object v = node.get();
522 524 if (v != null)
523 525 return v;
524 526 long now = System.nanoTime();
525 527 if (w == null)
526 528 w = Thread.currentThread();
527 529 else
528 530 nanos -= now - lastTime;
529 531 lastTime = now;
530 532 if (nanos > 0) {
531 533 if (spins > 0)
532 534 --spins;
533 535 else if (node.waiter == null)
534 536 node.waiter = w;
535 537 else if (w.isInterrupted())
536 538 tryCancel(node, slot);
537 539 else
538 540 LockSupport.parkNanos(node, nanos);
539 541 }
540 542 else if (tryCancel(node, slot) && !w.isInterrupted())
541 543 return scanOnTimeout(node);
542 544 }
543 545 }
544 546
545 547 /**
546 548 * Sweeps through arena checking for any waiting threads. Called
547 549 * only upon return from timeout while waiting in slot 0. When a
548 550 * thread gives up on a timed wait, it is possible that a
549 551 * previously-entered thread is still waiting in some other
550 552 * slot. So we scan to check for any. This is almost always
551 553 * overkill, but decreases the likelihood of timeouts when there
552 554 * are other threads present to far less than that in lock-based
553 555 * exchangers in which earlier-arriving threads may still be
554 556 * waiting on entry locks.
555 557 *
556 558 * @param node the waiting node
557 559 * @return another thread's item, or CANCEL
558 560 */
559 561 private Object scanOnTimeout(Node node) {
560 562 Object y;
561 563 for (int j = arena.length - 1; j >= 0; --j) {
562 564 Slot slot = arena[j];
563 565 if (slot != null) {
564 566 while ((y = slot.get()) != null) {
565 567 if (slot.compareAndSet(y, null)) {
566 568 Node you = (Node)y;
567 569 if (you.compareAndSet(null, node.item)) {
568 570 LockSupport.unpark(you.waiter);
569 571 return you.item;
570 572 }
571 573 }
572 574 }
573 575 }
574 576 }
575 577 return CANCEL;
576 578 }
577 579
578 580 /**
579 581 * Creates a new Exchanger.
580 582 */
581 583 public Exchanger() {
582 584 }
583 585
584 586 /**
585 587 * Waits for another thread to arrive at this exchange point (unless
586 588 * the current thread is {@linkplain Thread#interrupt interrupted}),
587 589 * and then transfers the given object to it, receiving its object
588 590 * in return.
589 591 *
↓ open down ↓ |
221 lines elided |
↑ open up ↑ |
590 592 * <p>If another thread is already waiting at the exchange point then
591 593 * it is resumed for thread scheduling purposes and receives the object
592 594 * passed in by the current thread. The current thread returns immediately,
593 595 * receiving the object passed to the exchange by that other thread.
594 596 *
595 597 * <p>If no other thread is already waiting at the exchange then the
596 598 * current thread is disabled for thread scheduling purposes and lies
597 599 * dormant until one of two things happens:
598 600 * <ul>
599 601 * <li>Some other thread enters the exchange; or
600 - * <li>Some other thread {@linkplain Thread#interrupt interrupts} the current
601 - * thread.
602 + * <li>Some other thread {@linkplain Thread#interrupt interrupts}
603 + * the current thread.
602 604 * </ul>
603 605 * <p>If the current thread:
604 606 * <ul>
605 607 * <li>has its interrupted status set on entry to this method; or
606 608 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
607 609 * for the exchange,
608 610 * </ul>
609 611 * then {@link InterruptedException} is thrown and the current thread's
610 612 * interrupted status is cleared.
611 613 *
612 614 * @param x the object to exchange
613 615 * @return the object provided by the other thread
614 616 * @throws InterruptedException if the current thread was
615 617 * interrupted while waiting
616 618 */
617 619 public V exchange(V x) throws InterruptedException {
618 620 if (!Thread.interrupted()) {
619 - Object v = doExchange(x == null? NULL_ITEM : x, false, 0);
621 + Object v = doExchange((x == null) ? NULL_ITEM : x, false, 0);
620 622 if (v == NULL_ITEM)
621 623 return null;
622 624 if (v != CANCEL)
623 625 return (V)v;
624 626 Thread.interrupted(); // Clear interrupt status on IE throw
625 627 }
626 628 throw new InterruptedException();
627 629 }
628 630
629 631 /**
630 632 * Waits for another thread to arrive at this exchange point (unless
631 633 * the current thread is {@linkplain Thread#interrupt interrupted} or
632 634 * the specified waiting time elapses), and then transfers the given
633 635 * object to it, receiving its object in return.
634 636 *
635 637 * <p>If another thread is already waiting at the exchange point then
636 638 * it is resumed for thread scheduling purposes and receives the object
637 639 * passed in by the current thread. The current thread returns immediately,
638 640 * receiving the object passed to the exchange by that other thread.
639 641 *
640 642 * <p>If no other thread is already waiting at the exchange then the
641 643 * current thread is disabled for thread scheduling purposes and lies
642 644 * dormant until one of three things happens:
643 645 * <ul>
644 646 * <li>Some other thread enters the exchange; or
645 647 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
646 648 * the current thread; or
647 649 * <li>The specified waiting time elapses.
648 650 * </ul>
649 651 * <p>If the current thread:
650 652 * <ul>
651 653 * <li>has its interrupted status set on entry to this method; or
652 654 * <li>is {@linkplain Thread#interrupt interrupted} while waiting
653 655 * for the exchange,
654 656 * </ul>
655 657 * then {@link InterruptedException} is thrown and the current thread's
656 658 * interrupted status is cleared.
657 659 *
658 660 * <p>If the specified waiting time elapses then {@link
659 661 * TimeoutException} is thrown. If the time is less than or equal
660 662 * to zero, the method will not wait at all.
661 663 *
662 664 * @param x the object to exchange
663 665 * @param timeout the maximum time to wait
↓ open down ↓ |
34 lines elided |
↑ open up ↑ |
664 666 * @param unit the time unit of the <tt>timeout</tt> argument
665 667 * @return the object provided by the other thread
666 668 * @throws InterruptedException if the current thread was
667 669 * interrupted while waiting
668 670 * @throws TimeoutException if the specified waiting time elapses
669 671 * before another thread enters the exchange
670 672 */
671 673 public V exchange(V x, long timeout, TimeUnit unit)
672 674 throws InterruptedException, TimeoutException {
673 675 if (!Thread.interrupted()) {
674 - Object v = doExchange(x == null? NULL_ITEM : x,
676 + Object v = doExchange((x == null) ? NULL_ITEM : x,
675 677 true, unit.toNanos(timeout));
676 678 if (v == NULL_ITEM)
677 679 return null;
678 680 if (v != CANCEL)
679 681 return (V)v;
680 682 if (!Thread.interrupted())
681 683 throw new TimeoutException();
682 684 }
683 685 throw new InterruptedException();
684 686 }
685 687 }
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX