228 *
229 * <pre> {@code
230 * void build(Task[] tasks, int lo, int hi, Phaser ph) {
231 * if (hi - lo > TASKS_PER_PHASER) {
232 * for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
233 * int j = Math.min(i + TASKS_PER_PHASER, hi);
234 * build(tasks, i, j, new Phaser(ph));
235 * }
236 * } else {
237 * for (int i = lo; i < hi; ++i)
238 * tasks[i] = new Task(ph);
239 * // assumes new Task(ph) performs ph.register()
240 * }
241 * }}</pre>
242 *
243 * The best value of {@code TASKS_PER_PHASER} depends mainly on
244 * expected synchronization rates. A value as low as four may
245 * be appropriate for extremely small per-phase task bodies (thus
246 * high rates), or up to hundreds for extremely large ones.
247 *
248 * <p><b>Implementation notes</b>: This implementation restricts the
249 * maximum number of parties to 65535. Attempts to register additional
250 * parties result in {@code IllegalStateException}. However, you can and
251 * should create tiered phasers to accommodate arbitrarily large sets
252 * of participants.
253 *
254 * @since 1.7
255 * @author Doug Lea
256 */
257 public class Phaser {
258 /*
259 * This class implements an extension of X10 "clocks". Thanks to
260 * Vijay Saraswat for the idea, and to Vivek Sarkar for
261 * enhancements to extend functionality.
262 */
263
264 /**
265 * Primary state representation, holding four bit-fields:
266 *
267 * unarrived -- the number of parties yet to hit barrier (bits 0-15)
268 * parties -- the number of parties to wait (bits 16-31)
902 * prevailing for the current transition. The effects of invoking
903 * arrival, registration, and waiting methods on this phaser from
904 * within {@code onAdvance} are unspecified and should not be
905 * relied on.
906 *
907 * <p>If this phaser is a member of a tiered set of phasers, then
908 * {@code onAdvance} is invoked only for its root phaser on each
909 * advance.
910 *
911 * <p>To support the most common use cases, the default
912 * implementation of this method returns {@code true} when the
913 * number of registered parties has become zero as the result of a
914 * party invoking {@code arriveAndDeregister}. You can disable
915 * this behavior, thus enabling continuation upon future
916 * registrations, by overriding this method to always return
917 * {@code false}:
918 *
919 * <pre> {@code
920 * Phaser phaser = new Phaser() {
921 * protected boolean onAdvance(int phase, int parties) { return false; }
922 * }}</pre>
923 *
924 * @param phase the current phase number on entry to this method,
925 * before this phaser is advanced
926 * @param registeredParties the current number of registered parties
927 * @return {@code true} if this phaser should terminate
928 */
929 protected boolean onAdvance(int phase, int registeredParties) {
930 return registeredParties == 0;
931 }
932
933 /**
934 * Returns a string identifying this phaser, as well as its
935 * state. The state, in brackets, includes the String {@code
936 * "phase = "} followed by the phase number, {@code "parties = "}
937 * followed by the number of registered parties, and {@code
938 * "arrived = "} followed by the number of arrived parties.
939 *
940 * @return a string identifying this phaser, as well as its state
941 */
942 public String toString() {
|
228 *
229 * <pre> {@code
230 * void build(Task[] tasks, int lo, int hi, Phaser ph) {
231 * if (hi - lo > TASKS_PER_PHASER) {
232 * for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
233 * int j = Math.min(i + TASKS_PER_PHASER, hi);
234 * build(tasks, i, j, new Phaser(ph));
235 * }
236 * } else {
237 * for (int i = lo; i < hi; ++i)
238 * tasks[i] = new Task(ph);
239 * // assumes new Task(ph) performs ph.register()
240 * }
241 * }}</pre>
242 *
243 * The best value of {@code TASKS_PER_PHASER} depends mainly on
244 * expected synchronization rates. A value as low as four may
245 * be appropriate for extremely small per-phase task bodies (thus
246 * high rates), or up to hundreds for extremely large ones.
247 *
248 * <p><b>Implementation notes:</b> This implementation restricts the
249 * maximum number of parties to 65535. Attempts to register additional
250 * parties result in {@code IllegalStateException}. However, you can and
251 * should create tiered phasers to accommodate arbitrarily large sets
252 * of participants.
253 *
254 * @since 1.7
255 * @author Doug Lea
256 */
257 public class Phaser {
258 /*
259 * This class implements an extension of X10 "clocks". Thanks to
260 * Vijay Saraswat for the idea, and to Vivek Sarkar for
261 * enhancements to extend functionality.
262 */
263
264 /**
265 * Primary state representation, holding four bit-fields:
266 *
267 * unarrived -- the number of parties yet to hit barrier (bits 0-15)
268 * parties -- the number of parties to wait (bits 16-31)
902 * prevailing for the current transition. The effects of invoking
903 * arrival, registration, and waiting methods on this phaser from
904 * within {@code onAdvance} are unspecified and should not be
905 * relied on.
906 *
907 * <p>If this phaser is a member of a tiered set of phasers, then
908 * {@code onAdvance} is invoked only for its root phaser on each
909 * advance.
910 *
911 * <p>To support the most common use cases, the default
912 * implementation of this method returns {@code true} when the
913 * number of registered parties has become zero as the result of a
914 * party invoking {@code arriveAndDeregister}. You can disable
915 * this behavior, thus enabling continuation upon future
916 * registrations, by overriding this method to always return
917 * {@code false}:
918 *
919 * <pre> {@code
920 * Phaser phaser = new Phaser() {
921 * protected boolean onAdvance(int phase, int parties) { return false; }
922 * };}</pre>
923 *
924 * @param phase the current phase number on entry to this method,
925 * before this phaser is advanced
926 * @param registeredParties the current number of registered parties
927 * @return {@code true} if this phaser should terminate
928 */
929 protected boolean onAdvance(int phase, int registeredParties) {
930 return registeredParties == 0;
931 }
932
933 /**
934 * Returns a string identifying this phaser, as well as its
935 * state. The state, in brackets, includes the String {@code
936 * "phase = "} followed by the phase number, {@code "parties = "}
937 * followed by the number of registered parties, and {@code
938 * "arrived = "} followed by the number of arrived parties.
939 *
940 * @return a string identifying this phaser, as well as its state
941 */
942 public String toString() {
|