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.23 by jsr166, Mon Jul 27 20:57:44 2009 UTC vs.
Revision 1.24 by jsr166, Mon Jul 27 21:41:53 2009 UTC

#	Line 32 | Line 32 | import java.util.concurrent.locks.LockSu
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 51 | Line 52 | import java.util.concurrent.locks.LockSu
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 75 | Line 76 | import java.util.concurrent.locks.LockSu
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 87 | Line 88 | import java.util.concurrent.locks.LockSu
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 139 | Line 140 | import java.util.concurrent.locks.LockSu
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 249 | 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 300 | 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 321 | 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 341 | 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 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

Diff Legend

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