ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/jsr166y/Phaser.java

Comparing jsr166/src/jsr166y/Phaser.java (file contents):
Revision 1.17 by jsr166, Thu Jul 23 19:25:45 2009 UTC vs.
Revision 1.24 by jsr166, Mon Jul 27 21:41:53 2009 UTC

#	Line 7 | Line 7
7		package jsr166y;
8
9		import java.util.concurrent.*;
10	<	import java.util.concurrent.atomic.*;
10	>
11	>	import java.util.concurrent.atomic.AtomicReference;
12		import java.util.concurrent.locks.LockSupport;
12	–	import sun.misc.Unsafe;
13	–	import java.lang.reflect.*;
13
14		/**
15		* A reusable synchronization barrier, similar in functionality to a
#	Line 33 | Line 32 | import java.lang.reflect.*;
32		* zero, and advancing when all parties reach the barrier (wrapping
33		* around to zero after reaching {@code Integer.MAX_VALUE}).
34		*
35	<	* <li> Like a CyclicBarrier, a Phaser may be repeatedly awaited.
36	<	* Method {@code arriveAndAwaitAdvance} has effect analogous to
37	<	* {@code CyclicBarrier.await}.  However, Phasers separate two
38	<	* aspects of coordination, that may also be invoked independently:
35	>	* <li> Like a {@code CyclicBarrier}, a Phaser may be repeatedly
36	>	* awaited.  Method {@link #arriveAndAwaitAdvance} has effect
37	>	* analogous to {@link java.util.concurrent.CyclicBarrier#await
38	>	* CyclicBarrier.await}.  However, phasers separate two aspects of
39	>	* coordination, that may also be invoked independently:
40		*
41		* <ul>
42		*
43	<	*   <li> Arriving at a barrier. Methods {@code arrive} and
44	<	*       {@code arriveAndDeregister} do not block, but return
43	>	*   <li> Arriving at a barrier. Methods {@link #arrive} and
44	>	*       {@link #arriveAndDeregister} do not block, but return
45		*       the phase value current upon entry to the method.
46		*
47	<	*   <li> Awaiting others. Method {@code awaitAdvance} requires an
47	>	*   <li> Awaiting others. Method {@link #awaitAdvance} requires an
48		*       argument indicating the entry phase, and returns when the
49		*       barrier advances to a new phase.
50		* </ul>
#	Line 52 | Line 52 | import java.lang.reflect.*;
52		*
53		* <li> Barrier actions, performed by the task triggering a phase
54		* advance while others may be waiting, are arranged by overriding
55	<	* method {@code onAdvance}, that also controls termination.
55	>	* method {@link #onAdvance}, that also controls termination.
56		* Overriding this method may be used to similar but more flexible
57	<	* effect as providing a barrier action to a CyclicBarrier.
57	>	* effect as providing a barrier action to a {@code CyclicBarrier}.
58		*
59		* <li> Phasers may enter a <em>termination</em> state in which all
60		* actions immediately return without updating phaser state or waiting
61		* for advance, and indicating (via a negative phase value) that
62		* execution is complete.  Termination is triggered by executing the
63		* overridable {@code onAdvance} method that is invoked each time the
64	<	* barrier is about to be tripped. When a Phaser is controlling an
64	>	* barrier is about to be tripped. When a phaser is controlling an
65		* action with a fixed number of iterations, it is often convenient to
66		* override this method to cause termination when the current phase
67	<	* number reaches a threshold. Method {@code forceTermination} is also
67	>	* number reaches a threshold. Method {@link #forceTermination} is also
68		* available to abruptly release waiting threads and allow them to
69		* terminate.
70		*
#	Line 76 | Line 76 | import java.lang.reflect.*;
76		*
77		* <li> By default, {@code awaitAdvance} continues to wait even if
78		* the waiting thread is interrupted. And unlike the case in
79	<	* CyclicBarriers, exceptions encountered while tasks wait
79	>	* {@code CyclicBarrier}, exceptions encountered while tasks wait
80		* interruptibly or with timeout do not change the state of the
81		* barrier. If necessary, you can perform any associated recovery
82		* within handlers of those exceptions, often after invoking
#	Line 88 | Line 88 | import java.lang.reflect.*;
88		*
89		* <p><b>Sample usages:</b>
90		*
91	<	* <p>A Phaser may be used instead of a {@code CountDownLatch} to control
92	<	* a one-shot action serving a variable number of parties. The typical
93	<	* idiom is for the method setting this up to first register, then
94	<	* start the actions, then deregister, as in:
91	>	* <p>A {@code Phaser} may be used instead of a {@code CountDownLatch}
92	>	* to control a one-shot action serving a variable number of
93	>	* parties. The typical idiom is for the method setting this up to
94	>	* first register, then start the actions, then deregister, as in:
95		*
96		*  <pre> {@code
97		* void runTasks(List<Runnable> list) {
#	Line 140 | Line 140 | import java.lang.reflect.*;
140		*   phaser.arriveAndDeregister(); // deregister self, don't wait
141		* }}</pre>
142		*
143	<	* <p> To create a set of tasks using a tree of Phasers,
143	>	* <p> To create a set of tasks using a tree of phasers,
144		* you could use code of the following form, assuming a
145	<	* Task class with a constructor accepting a Phaser that
145	>	* Task class with a constructor accepting a phaser that
146		* it registers for upon construction:
147		*  <pre> {@code
148		* void build(Task[] actions, int lo, int hi, Phaser b) {
#	Line 211 | Line 211 | public class Phaser {
211		private static final int phaseMask  = 0x7fffffff;
212
213		private static int unarrivedOf(long s) {
214	<	return (int)(s & ushortMask);
214	>	return (int) (s & ushortMask);
215		}
216
217		private static int partiesOf(long s) {
#	Line 250 | Line 250 | public class Phaser {
250		private final Phaser parent;
251
252		/**
253	<	* The root of Phaser tree. Equals this if not in a tree.  Used to
253	>	* The root of phaser tree. Equals this if not in a tree.  Used to
254		* support faster state push-down.
255		*/
256		private final Phaser root;
#	Line 266 | Line 266 | public class Phaser {
266		private final AtomicReference<QNode> oddQ  = new AtomicReference<QNode>();
267
268		private AtomicReference<QNode> queueFor(int phase) {
269	<	return (phase & 1) == 0? evenQ : oddQ;
269	>	return ((phase & 1) == 0) ? evenQ : oddQ;
270		}
271
272		/**
#	Line 274 | Line 274 | public class Phaser {
274		* root if necessary.
275		*/
276		private long getReconciledState() {
277	<	return parent == null? state : reconcileState();
277	>	return (parent == null) ? state : reconcileState();
278		}
279
280		/**
#	Line 301 | Line 301 | public class Phaser {
301		}
302
303		/**
304	<	* Creates a new Phaser without any initially registered parties,
304	>	* Creates a new phaser without any initially registered parties,
305		* initial phase number 0, and no parent. Any thread using this
306	<	* Phaser will need to first register for it.
306	>	* phaser will need to first register for it.
307		*/
308		public Phaser() {
309		this(null);
310		}
311
312		/**
313	<	* Creates a new Phaser with the given numbers of registered
313	>	* Creates a new phaser with the given numbers of registered
314		* unarrived parties, initial phase number 0, and no parent.
315		*
316		* @param parties the number of parties required to trip barrier
#	Line 322 | Line 322 | public class Phaser {
322		}
323
324		/**
325	<	* Creates a new Phaser with the given parent, without any
325	>	* Creates a new phaser with the given parent, without any
326		* initially registered parties. If parent is non-null this phaser
327		* is registered with the parent and its initial phase number is
328		* the same as that of parent phaser.
#	Line 342 | Line 342 | public class Phaser {
342		}
343
344		/**
345	<	* Creates a new Phaser with the given parent and numbers of
345	>	* Creates a new phaser with the given parent and numbers of
346		* registered unarrived parties. If parent is non-null, this phaser
347		* is registered with the parent and its initial phase number is
348		* the same as that of parent phaser.
#	Line 441 | Line 441 | public class Phaser {
441		if (par == null) {      // directly trip
442		if (casState
443		(s,
444	<	trippedStateFor(onAdvance(phase, parties)? -1 :
444	>	trippedStateFor(onAdvance(phase, parties) ? -1 :
445		((phase + 1) & phaseMask), parties))) {
446		releaseWaiters(phase);
447		break;
#	Line 502 | Line 502 | public class Phaser {
502		if (unarrived == 0) {
503		if (casState
504		(s,
505	<	trippedStateFor(onAdvance(phase, parties)? -1 :
505	>	trippedStateFor(onAdvance(phase, parties) ? -1 :
506		((phase + 1) & phaseMask), parties))) {
507		releaseWaiters(phase);
508		break;
#	Line 587 | Line 587 | public class Phaser {
587		* @throws InterruptedException if thread interrupted while waiting
588		* @throws TimeoutException if timed out while waiting
589		*/
590	<	public int awaitAdvanceInterruptibly(int phase, long timeout, TimeUnit unit)
590	>	public int awaitAdvanceInterruptibly(int phase,
591	>	long timeout, TimeUnit unit)
592		throws InterruptedException, TimeoutException {
593		if (phase < 0)
594		return phase;
#	Line 675 | Line 676 | public class Phaser {
676		}
677
678		/**
679	<	* Returns the parent of this phaser, or null if none.
679	>	* Returns the parent of this phaser, or {@code null} if none.
680		*
681	<	* @return the parent of this phaser, or null if none
681	>	* @return the parent of this phaser, or {@code null} if none
682		*/
683		public Phaser getParent() {
684		return parent;
#	Line 706 | Line 707 | public class Phaser {
707		* Overridable method to perform an action upon phase advance, and
708		* to control termination. This method is invoked whenever the
709		* barrier is tripped (and thus all other waiting parties are
710	<	* dormant). If it returns true, then, rather than advance the
711	<	* phase number, this barrier will be set to a final termination
712	<	* state, and subsequent calls to {@code isTerminated} will
713	<	* return true.
710	>	* dormant). If it returns {@code true}, then, rather than advance
711	>	* the phase number, this barrier will be set to a final
712	>	* termination state, and subsequent calls to {@link #isTerminated}
713	>	* will return true.
714		*
715	<	* <p> The default version returns true when the number of
715	>	* <p> The default version returns {@code true} when the number of
716		* registered parties is zero. Normally, overrides that arrange
717		* termination for other reasons should also preserve this
718		* property.
#	Line 719 | Line 720 | public class Phaser {
720		* <p> You may override this method to perform an action with side
721		* effects visible to participating tasks, but it is in general
722		* only sensible to do so in designs where all parties register
723	<	* before any arrive, and all {@code awaitAdvance} at each phase.
723	>	* before any arrive, and all {@link #awaitAdvance} at each phase.
724		* Otherwise, you cannot ensure lack of interference. In
725		* particular, this method may be invoked more than once per
726		* transition if other parties successfully register while the
#	Line 930 | Line 931 | public class Phaser {
931		return p;
932		}
933
934	<	// Temporary Unsafe mechanics for preliminary release
934	<	private static Unsafe getUnsafe() throws Throwable {
935	<	try {
936	<	return Unsafe.getUnsafe();
937	<	} catch (SecurityException se) {
938	<	try {
939	<	return java.security.AccessController.doPrivileged
940	<	(new java.security.PrivilegedExceptionAction<Unsafe>() {
941	<	public Unsafe run() throws Exception {
942	<	return getUnsafePrivileged();
943	<	}});
944	<	} catch (java.security.PrivilegedActionException e) {
945	<	throw e.getCause();
946	<	}
947	<	}
948	<	}
934	>	// Unsafe mechanics
935
936	<	private static Unsafe getUnsafePrivileged()
937	<	throws NoSuchFieldException, IllegalAccessException {
938	<	Field f = Unsafe.class.getDeclaredField("theUnsafe");
953	<	f.setAccessible(true);
954	<	return (Unsafe) f.get(null);
955	<	}
936	>	private static final sun.misc.Unsafe UNSAFE = getUnsafe();
937	>	private static final long stateOffset =
938	>	objectFieldOffset("state", Phaser.class);
939
940	<	private static long fieldOffset(String fieldName)
941	<	throws NoSuchFieldException {
959	<	return UNSAFE.objectFieldOffset
960	<	(Phaser.class.getDeclaredField(fieldName));
940	>	private final boolean casState(long cmp, long val) {
941	>	return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val);
942		}
943
944	<	static final Unsafe UNSAFE;
964	<	static final long stateOffset;
965	<
966	<	static {
944	>	private static long objectFieldOffset(String field, Class<?> klazz) {
945		try {
946	<	UNSAFE = getUnsafe();
947	<	stateOffset = fieldOffset("state");
948	<	} catch (Throwable e) {
949	<	throw new RuntimeException("Could not initialize intrinsics", e);
946	>	return UNSAFE.objectFieldOffset(klazz.getDeclaredField(field));
947	>	} catch (NoSuchFieldException e) {
948	>	// Convert Exception to corresponding Error
949	>	NoSuchFieldError error = new NoSuchFieldError(field);
950	>	error.initCause(e);
951	>	throw error;
952		}
953		}
954
955	<	final boolean casState(long cmp, long val) {
956	<	return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val);
955	>	/**
956	>	* Returns a sun.misc.Unsafe.  Suitable for use in a 3rd party package.
957	>	* Replace with a simple call to Unsafe.getUnsafe when integrating
958	>	* into a jdk.
959	>	*
960	>	* @return a sun.misc.Unsafe
961	>	*/
962	>	private static sun.misc.Unsafe getUnsafe() {
963	>	try {
964	>	return sun.misc.Unsafe.getUnsafe();
965	>	} catch (SecurityException se) {
966	>	try {
967	>	return java.security.AccessController.doPrivileged
968	>	(new java.security
969	>	.PrivilegedExceptionAction<sun.misc.Unsafe>() {
970	>	public sun.misc.Unsafe run() throws Exception {
971	>	java.lang.reflect.Field f = sun.misc
972	>	.Unsafe.class.getDeclaredField("theUnsafe");
973	>	f.setAccessible(true);
974	>	return (sun.misc.Unsafe) f.get(null);
975	>	}});
976	>	} catch (java.security.PrivilegedActionException e) {
977	>	throw new RuntimeException("Could not initialize intrinsics",
978	>	e.getCause());
979	>	}
980	>	}
981		}
982		}

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines