| 18 |
|
* but supporting more flexible usage. |
| 19 |
|
* |
| 20 |
|
* <p> <b>Registration.</b> Unlike the case for other barriers, the |
| 21 |
< |
* number of parties <em>registered</em> to synchronize on a Phaser |
| 21 |
> |
* number of parties <em>registered</em> to synchronize on a phaser |
| 22 |
|
* may vary over time. Tasks may be registered at any time (using |
| 23 |
|
* methods {@link #register}, {@link #bulkRegister}, or forms of |
| 24 |
|
* constructors establishing initial numbers of parties), and |
| 34 |
|
* Phaser} may be repeatedly awaited. Method {@link |
| 35 |
|
* #arriveAndAwaitAdvance} has effect analogous to {@link |
| 36 |
|
* java.util.concurrent.CyclicBarrier#await CyclicBarrier.await}. Each |
| 37 |
< |
* generation of a {@code Phaser} has an associated phase number. The |
| 38 |
< |
* phase number starts at zero, and advances when all parties arrive |
| 39 |
< |
* at the barrier, wrapping around to zero after reaching {@code |
| 37 |
> |
* generation of a phaser has an associated phase number. The phase |
| 38 |
> |
* number starts at zero, and advances when all parties arrive at the |
| 39 |
> |
* phaser, wrapping around to zero after reaching {@code |
| 40 |
|
* Integer.MAX_VALUE}. The use of phase numbers enables independent |
| 41 |
< |
* control of actions upon arrival at a barrier and upon awaiting |
| 41 |
> |
* control of actions upon arrival at a phaser and upon awaiting |
| 42 |
|
* others, via two kinds of methods that may be invoked by any |
| 43 |
|
* registered party: |
| 44 |
|
* |
| 45 |
|
* <ul> |
| 46 |
|
* |
| 47 |
|
* <li> <b>Arrival.</b> Methods {@link #arrive} and |
| 48 |
< |
* {@link #arriveAndDeregister} record arrival at a |
| 49 |
< |
* barrier. These methods do not block, but return an associated |
| 50 |
< |
* <em>arrival phase number</em>; that is, the phase number of |
| 51 |
< |
* the barrier to which the arrival applied. When the final |
| 52 |
< |
* party for a given phase arrives, an optional barrier action |
| 53 |
< |
* is performed and the phase advances. Barrier actions, |
| 54 |
< |
* performed by the party triggering a phase advance, are |
| 55 |
< |
* arranged by overriding method {@link #onAdvance(int, int)}, |
| 56 |
< |
* which also controls termination. Overriding this method is |
| 57 |
< |
* similar to, but more flexible than, providing a barrier |
| 58 |
< |
* action to a {@code CyclicBarrier}. |
| 48 |
> |
* {@link #arriveAndDeregister} record arrival. These methods |
| 49 |
> |
* do not block, but return an associated <em>arrival phase |
| 50 |
> |
* number</em>; that is, the phase number of the phaser to which |
| 51 |
> |
* the arrival applied. When the final party for a given phase |
| 52 |
> |
* arrives, an optional action is performed and the phase |
| 53 |
> |
* advances. These actions are performed by the party |
| 54 |
> |
* triggering a phase advance, and are arranged by overriding |
| 55 |
> |
* method {@link #onAdvance(int, int)}, which also controls |
| 56 |
> |
* termination. Overriding this method is similar to, but more |
| 57 |
> |
* flexible than, providing a barrier action to a {@code |
| 58 |
> |
* CyclicBarrier}. |
| 59 |
|
* |
| 60 |
|
* <li> <b>Waiting.</b> Method {@link #awaitAdvance} requires an |
| 61 |
|
* argument indicating an arrival phase number, and returns when |
| 62 |
< |
* the barrier advances to (or is already at) a different phase. |
| 62 |
> |
* the phaser advances to (or is already at) a different phase. |
| 63 |
|
* Unlike similar constructions using {@code CyclicBarrier}, |
| 64 |
|
* method {@code awaitAdvance} continues to wait even if the |
| 65 |
|
* waiting thread is interrupted. Interruptible and timeout |
| 66 |
|
* versions are also available, but exceptions encountered while |
| 67 |
|
* tasks wait interruptibly or with timeout do not change the |
| 68 |
< |
* state of the barrier. If necessary, you can perform any |
| 68 |
> |
* state of the phaser. If necessary, you can perform any |
| 69 |
|
* associated recovery within handlers of those exceptions, |
| 70 |
|
* often after invoking {@code forceTermination}. Phasers may |
| 71 |
|
* also be used by tasks executing in a {@link ForkJoinPool}, |
| 74 |
|
* |
| 75 |
|
* </ul> |
| 76 |
|
* |
| 77 |
< |
* <p> <b>Termination.</b> A {@code Phaser} may enter a |
| 78 |
< |
* <em>termination</em> state in which all synchronization methods |
| 79 |
< |
* immediately return without updating Phaser state or waiting for |
| 80 |
< |
* advance, and indicating (via a negative phase value) that execution |
| 81 |
< |
* is complete. Termination is triggered when an invocation of {@code |
| 82 |
< |
* onAdvance} returns {@code true}. The default implementation returns |
| 83 |
< |
* {@code true} if a deregistration has caused the number of |
| 84 |
< |
* registered parties to become zero. As illustrated below, when |
| 85 |
< |
* Phasers control actions with a fixed number of iterations, it is |
| 86 |
< |
* often convenient to override this method to cause termination when |
| 87 |
< |
* the current phase number reaches a threshold. Method {@link |
| 88 |
< |
* #forceTermination} is also available to abruptly release waiting |
| 89 |
< |
* threads and allow them to terminate. |
| 77 |
> |
* <p> <b>Termination.</b> A phaser may enter a <em>termination</em> |
| 78 |
> |
* state in which all synchronization methods immediately return |
| 79 |
> |
* without updating phaser state or waiting for advance, and |
| 80 |
> |
* indicating (via a negative phase value) that execution is complete. |
| 81 |
> |
* Termination is triggered when an invocation of {@code onAdvance} |
| 82 |
> |
* returns {@code true}. The default implementation returns {@code |
| 83 |
> |
* true} if a deregistration has caused the number of registered |
| 84 |
> |
* parties to become zero. As illustrated below, when phasers control |
| 85 |
> |
* actions with a fixed number of iterations, it is often convenient |
| 86 |
> |
* to override this method to cause termination when the current phase |
| 87 |
> |
* number reaches a threshold. Method {@link #forceTermination} is |
| 88 |
> |
* also available to abruptly release waiting threads and allow them |
| 89 |
> |
* to terminate. |
| 90 |
|
* |
| 91 |
|
* <p> <b>Tiering.</b> Phasers may be <em>tiered</em> (i.e., |
| 92 |
|
* constructed in tree structures) to reduce contention. Phasers with |
| 97 |
|
* overhead. |
| 98 |
|
* |
| 99 |
|
* <p><b>Monitoring.</b> While synchronization methods may be invoked |
| 100 |
< |
* only by registered parties, the current state of a Phaser may be |
| 100 |
> |
* only by registered parties, the current state of a phaser may be |
| 101 |
|
* monitored by any caller. At any given moment there are {@link |
| 102 |
|
* #getRegisteredParties} parties in total, of which {@link |
| 103 |
|
* #getArrivedParties} have arrived at the current phase ({@link |
| 183 |
|
* }}</pre> |
| 184 |
|
* |
| 185 |
|
* |
| 186 |
< |
* <p>To create a set of tasks using a tree of Phasers, |
| 186 |
> |
* <p>To create a set of tasks using a tree of phasers, |
| 187 |
|
* you could use code of the following form, assuming a |
| 188 |
< |
* Task class with a constructor accepting a Phaser that |
| 188 |
> |
* Task class with a constructor accepting a {@code Phaser} that |
| 189 |
|
* it registers with upon construction: |
| 190 |
|
* |
| 191 |
|
* <pre> {@code |
| 205 |
|
* build(new Task[n], 0, n, new Phaser());}</pre> |
| 206 |
|
* |
| 207 |
|
* The best value of {@code TASKS_PER_PHASER} depends mainly on |
| 208 |
< |
* expected barrier synchronization rates. A value as low as four may |
| 209 |
< |
* be appropriate for extremely small per-barrier task bodies (thus |
| 208 |
> |
* expected synchronization rates. A value as low as four may |
| 209 |
> |
* be appropriate for extremely small per-phase task bodies (thus |
| 210 |
|
* high rates), or up to hundreds for extremely large ones. |
| 211 |
|
* |
| 212 |
|
* <p><b>Implementation notes</b>: This implementation restricts the |
| 213 |
|
* maximum number of parties to 65535. Attempts to register additional |
| 214 |
|
* parties result in {@code IllegalStateException}. However, you can and |
| 215 |
< |
* should create tiered Phasers to accommodate arbitrarily large sets |
| 215 |
> |
* should create tiered phasers to accommodate arbitrarily large sets |
| 216 |
|
* of participants. |
| 217 |
|
* |
| 218 |
|
* @since 1.7 |
| 226 |
|
*/ |
| 227 |
|
|
| 228 |
|
/** |
| 229 |
< |
* Barrier state representation. Conceptually, a barrier contains |
| 230 |
< |
* four values: |
| 229 |
> |
* Primary state representation, holding four fields: |
| 230 |
|
* |
| 231 |
|
* * unarrived -- the number of parties yet to hit barrier (bits 0-15) |
| 232 |
|
* * parties -- the number of parties to wait (bits 16-31) |
| 427 |
|
} |
| 428 |
|
|
| 429 |
|
/** |
| 430 |
< |
* Creates a new Phaser without any initially registered parties, |
| 431 |
< |
* initial phase number 0, and no parent. Any thread using this |
| 432 |
< |
* Phaser will need to first register for it. |
| 430 |
> |
* Creates a new phaser with no initially registered parties, no |
| 431 |
> |
* parent, and initial phase number 0. Any thread using this |
| 432 |
> |
* phaser will need to first register for it. |
| 433 |
|
*/ |
| 434 |
|
public Phaser() { |
| 435 |
|
this(null, 0); |
| 436 |
|
} |
| 437 |
|
|
| 438 |
|
/** |
| 439 |
< |
* Creates a new Phaser with the given number of registered |
| 440 |
< |
* unarrived parties, initial phase number 0, and no parent. |
| 439 |
> |
* Creates a new phaser with the given number of registered |
| 440 |
> |
* unarrived parties, no parent, and initial phase number 0. |
| 441 |
|
* |
| 442 |
< |
* @param parties the number of parties required to trip barrier |
| 442 |
> |
* @param parties the number of parties required to advance to the |
| 443 |
> |
* next phase |
| 444 |
|
* @throws IllegalArgumentException if parties less than zero |
| 445 |
|
* or greater than the maximum number of parties supported |
| 446 |
|
*/ |
| 451 |
|
/** |
| 452 |
|
* Equivalent to {@link #Phaser(Phaser, int) Phaser(parent, 0)}. |
| 453 |
|
* |
| 454 |
< |
* @param parent the parent Phaser |
| 454 |
> |
* @param parent the parent phaser |
| 455 |
|
*/ |
| 456 |
|
public Phaser(Phaser parent) { |
| 457 |
|
this(parent, 0); |
| 458 |
|
} |
| 459 |
|
|
| 460 |
|
/** |
| 461 |
< |
* Creates a new Phaser with the given parent and number of |
| 461 |
> |
* Creates a new phaser with the given parent and number of |
| 462 |
|
* registered unarrived parties. Registration and deregistration |
| 463 |
< |
* of this child Phaser with its parent are managed automatically. |
| 464 |
< |
* If the given parent is non-null, whenever this child Phaser has |
| 463 |
> |
* of this child phaser with its parent are managed automatically. |
| 464 |
> |
* If the given parent is non-null, whenever this child phaser has |
| 465 |
|
* any registered parties (as established in this constructor, |
| 466 |
< |
* {@link #register}, or {@link #bulkRegister}), this child Phaser |
| 466 |
> |
* {@link #register}, or {@link #bulkRegister}), this child phaser |
| 467 |
|
* is registered with its parent. Whenever the number of |
| 468 |
|
* registered parties becomes zero as the result of an invocation |
| 469 |
< |
* of {@link #arriveAndDeregister}, this child Phaser is |
| 469 |
> |
* of {@link #arriveAndDeregister}, this child phaser is |
| 470 |
|
* deregistered from its parent. |
| 471 |
|
* |
| 472 |
< |
* @param parent the parent Phaser |
| 473 |
< |
* @param parties the number of parties required to trip barrier |
| 472 |
> |
* @param parent the parent phaser |
| 473 |
> |
* @param parties the number of parties required to advance to the |
| 474 |
> |
* next phase |
| 475 |
|
* @throws IllegalArgumentException if parties less than zero |
| 476 |
|
* or greater than the maximum number of parties supported |
| 477 |
|
*/ |
| 497 |
|
} |
| 498 |
|
|
| 499 |
|
/** |
| 500 |
< |
* Adds a new unarrived party to this Phaser. If an ongoing |
| 500 |
> |
* Adds a new unarrived party to this phaser. If an ongoing |
| 501 |
|
* invocation of {@link #onAdvance} is in progress, this method |
| 502 |
< |
* may await its completion before returning. If this Phaser has |
| 503 |
< |
* a parent, and this Phaser previously had no registered parties, |
| 504 |
< |
* this Phaser is also registered with its parent. |
| 502 |
> |
* may await its completion before returning. If this phaser has |
| 503 |
> |
* a parent, and this phaser previously had no registered parties, |
| 504 |
> |
* this phaser is also registered with its parent. |
| 505 |
|
* |
| 506 |
|
* @return the arrival phase number to which this registration applied |
| 507 |
|
* @throws IllegalStateException if attempting to register more |
| 512 |
|
} |
| 513 |
|
|
| 514 |
|
/** |
| 515 |
< |
* Adds the given number of new unarrived parties to this Phaser. |
| 515 |
> |
* Adds the given number of new unarrived parties to this phaser. |
| 516 |
|
* If an ongoing invocation of {@link #onAdvance} is in progress, |
| 517 |
|
* this method may await its completion before returning. If this |
| 518 |
< |
* Phaser has a parent, and the given number of parities is |
| 519 |
< |
* greater than zero, and this Phaser previously had no registered |
| 520 |
< |
* parties, this Phaser is also registered with its parent. |
| 518 |
> |
* phaser has a parent, and the given number of parities is |
| 519 |
> |
* greater than zero, and this phaser previously had no registered |
| 520 |
> |
* parties, this phaser is also registered with its parent. |
| 521 |
|
* |
| 522 |
< |
* @param parties the number of additional parties required to trip barrier |
| 522 |
> |
* @param parties the number of additional parties required to |
| 523 |
> |
* advance to the next phase |
| 524 |
|
* @return the arrival phase number to which this registration applied |
| 525 |
|
* @throws IllegalStateException if attempting to register more |
| 526 |
|
* than the maximum supported number of parties |
| 535 |
|
} |
| 536 |
|
|
| 537 |
|
/** |
| 538 |
< |
* Arrives at the barrier, without waiting for others to arrive. |
| 538 |
> |
* Arrives at this phaser, without waiting for others to arrive. |
| 539 |
|
* |
| 540 |
|
* <p>It is a usage error for an unregistered party to invoke this |
| 541 |
|
* method. However, this error may result in an {@code |
| 542 |
|
* IllegalStateException} only upon some subsequent operation on |
| 543 |
< |
* this Phaser, if ever. |
| 543 |
> |
* this phaser, if ever. |
| 544 |
|
* |
| 545 |
|
* @return the arrival phase number, or a negative value if terminated |
| 546 |
|
* @throws IllegalStateException if not terminated and the number |
| 551 |
|
} |
| 552 |
|
|
| 553 |
|
/** |
| 554 |
< |
* Arrives at the barrier and deregisters from it without waiting |
| 554 |
> |
* Arrives at this phaser and deregisters from it without waiting |
| 555 |
|
* for others to arrive. Deregistration reduces the number of |
| 556 |
< |
* parties required to trip the barrier in future phases. If this |
| 557 |
< |
* Phaser has a parent, and deregistration causes this Phaser to |
| 558 |
< |
* have zero parties, this Phaser is also deregistered from its |
| 557 |
< |
* parent. |
| 556 |
> |
* parties required to advance in future phases. If this phaser |
| 557 |
> |
* has a parent, and deregistration causes this phaser to have |
| 558 |
> |
* zero parties, this phaser is also deregistered from its parent. |
| 559 |
|
* |
| 560 |
|
* <p>It is a usage error for an unregistered party to invoke this |
| 561 |
|
* method. However, this error may result in an {@code |
| 562 |
|
* IllegalStateException} only upon some subsequent operation on |
| 563 |
< |
* this Phaser, if ever. |
| 563 |
> |
* this phaser, if ever. |
| 564 |
|
* |
| 565 |
|
* @return the arrival phase number, or a negative value if terminated |
| 566 |
|
* @throws IllegalStateException if not terminated and the number |
| 571 |
|
} |
| 572 |
|
|
| 573 |
|
/** |
| 574 |
< |
* Arrives at the barrier and awaits others. Equivalent in effect |
| 574 |
> |
* Arrives at this phaser and awaits others. Equivalent in effect |
| 575 |
|
* to {@code awaitAdvance(arrive())}. If you need to await with |
| 576 |
|
* interruption or timeout, you can arrange this with an analogous |
| 577 |
|
* construction using one of the other forms of the {@code |
| 581 |
|
* <p>It is a usage error for an unregistered party to invoke this |
| 582 |
|
* method. However, this error may result in an {@code |
| 583 |
|
* IllegalStateException} only upon some subsequent operation on |
| 584 |
< |
* this Phaser, if ever. |
| 584 |
> |
* this phaser, if ever. |
| 585 |
|
* |
| 586 |
|
* @return the arrival phase number, or a negative number if terminated |
| 587 |
|
* @throws IllegalStateException if not terminated and the number |
| 592 |
|
} |
| 593 |
|
|
| 594 |
|
/** |
| 595 |
< |
* Awaits the phase of the barrier to advance from the given phase |
| 596 |
< |
* value, returning immediately if the current phase of the |
| 597 |
< |
* barrier is not equal to the given phase value or this barrier |
| 597 |
< |
* is terminated. |
| 595 |
> |
* Awaits the phase of this phaser to advance from the given phase |
| 596 |
> |
* value, returning immediately if the current phase is not equal |
| 597 |
> |
* to the given phase value or this phaser is terminated. |
| 598 |
|
* |
| 599 |
|
* @param phase an arrival phase number, or negative value if |
| 600 |
|
* terminated; this argument is normally the value returned by a |
| 601 |
< |
* previous call to {@code arrive} or its variants |
| 601 |
> |
* previous call to {@code arrive} or {@code arriveAndDeregister}. |
| 602 |
|
* @return the next arrival phase number, or a negative value |
| 603 |
|
* if terminated or argument is negative |
| 604 |
|
*/ |
| 614 |
|
} |
| 615 |
|
|
| 616 |
|
/** |
| 617 |
< |
* Awaits the phase of the barrier to advance from the given phase |
| 617 |
> |
* Awaits the phase of this phaser to advance from the given phase |
| 618 |
|
* value, throwing {@code InterruptedException} if interrupted |
| 619 |
< |
* while waiting, or returning immediately if the current phase of |
| 620 |
< |
* the barrier is not equal to the given phase value or this |
| 621 |
< |
* barrier is terminated. |
| 619 |
> |
* while waiting, or returning immediately if the current phase is |
| 620 |
> |
* not equal to the given phase value or this phaser is |
| 621 |
> |
* terminated. |
| 622 |
|
* |
| 623 |
|
* @param phase an arrival phase number, or negative value if |
| 624 |
|
* terminated; this argument is normally the value returned by a |
| 625 |
< |
* previous call to {@code arrive} or its variants |
| 625 |
> |
* previous call to {@code arrive} or {@code arriveAndDeregister}. |
| 626 |
|
* @return the next arrival phase number, or a negative value |
| 627 |
|
* if terminated or argument is negative |
| 628 |
|
* @throws InterruptedException if thread interrupted while waiting |
| 644 |
|
} |
| 645 |
|
|
| 646 |
|
/** |
| 647 |
< |
* Awaits the phase of the barrier to advance from the given phase |
| 647 |
> |
* Awaits the phase of this phaser to advance from the given phase |
| 648 |
|
* value or the given timeout to elapse, throwing {@code |
| 649 |
|
* InterruptedException} if interrupted while waiting, or |
| 650 |
< |
* returning immediately if the current phase of the barrier is |
| 651 |
< |
* not equal to the given phase value or this barrier is |
| 652 |
< |
* terminated. |
| 650 |
> |
* returning immediately if the current phase is not equal to the |
| 651 |
> |
* given phase value or this phaser is terminated. |
| 652 |
|
* |
| 653 |
|
* @param phase an arrival phase number, or negative value if |
| 654 |
|
* terminated; this argument is normally the value returned by a |
| 655 |
< |
* previous call to {@code arrive} or its variants |
| 655 |
> |
* previous call to {@code arrive} or {@code arriveAndDeregister}. |
| 656 |
|
* @param timeout how long to wait before giving up, in units of |
| 657 |
|
* {@code unit} |
| 658 |
|
* @param unit a {@code TimeUnit} determining how to interpret the |
| 683 |
|
} |
| 684 |
|
|
| 685 |
|
/** |
| 686 |
< |
* Forces this barrier to enter termination state. Counts of |
| 687 |
< |
* arrived and registered parties are unaffected. If this Phaser |
| 688 |
< |
* is a member of a tiered set of Phasers, then all of the Phasers |
| 689 |
< |
* in the set are terminated. If this Phaser is already |
| 686 |
> |
* Forces this phaser to enter termination state. Counts of |
| 687 |
> |
* arrived and registered parties are unaffected. If this phaser |
| 688 |
> |
* is a member of a tiered set of phasers, then all of the phasers |
| 689 |
> |
* in the set are terminated. If this phaser is already |
| 690 |
|
* terminated, this method has no effect. This method may be |
| 691 |
|
* useful for coordinating recovery after one or more tasks |
| 692 |
|
* encounter unexpected exceptions. |
| 708 |
|
/** |
| 709 |
|
* Returns the current phase number. The maximum phase number is |
| 710 |
|
* {@code Integer.MAX_VALUE}, after which it restarts at |
| 711 |
< |
* zero. Upon termination, the phase number is negative. |
| 711 |
> |
* zero. Upon termination, the phase number is negative, |
| 712 |
> |
* in which case the prevailing phase prior to termination |
| 713 |
> |
* may be obtained via {@code getPhase() + Integer.MIN_VALUE}. |
| 714 |
|
* |
| 715 |
|
* @return the phase number, or a negative value if terminated |
| 716 |
|
*/ |
| 719 |
|
} |
| 720 |
|
|
| 721 |
|
/** |
| 722 |
< |
* Returns the number of parties registered at this barrier. |
| 722 |
> |
* Returns the number of parties registered at this phaser. |
| 723 |
|
* |
| 724 |
|
* @return the number of parties |
| 725 |
|
*/ |
| 729 |
|
|
| 730 |
|
/** |
| 731 |
|
* Returns the number of registered parties that have arrived at |
| 732 |
< |
* the current phase of this barrier. |
| 732 |
> |
* the current phase of this phaser. |
| 733 |
|
* |
| 734 |
|
* @return the number of arrived parties |
| 735 |
|
*/ |
| 743 |
|
|
| 744 |
|
/** |
| 745 |
|
* Returns the number of registered parties that have not yet |
| 746 |
< |
* arrived at the current phase of this barrier. |
| 746 |
> |
* arrived at the current phase of this phaser. |
| 747 |
|
* |
| 748 |
|
* @return the number of unarrived parties |
| 749 |
|
*/ |
| 753 |
|
} |
| 754 |
|
|
| 755 |
|
/** |
| 756 |
< |
* Returns the parent of this Phaser, or {@code null} if none. |
| 756 |
> |
* Returns the parent of this phaser, or {@code null} if none. |
| 757 |
|
* |
| 758 |
< |
* @return the parent of this Phaser, or {@code null} if none |
| 758 |
> |
* @return the parent of this phaser, or {@code null} if none |
| 759 |
|
*/ |
| 760 |
|
public Phaser getParent() { |
| 761 |
|
return parent; |
| 762 |
|
} |
| 763 |
|
|
| 764 |
|
/** |
| 765 |
< |
* Returns the root ancestor of this Phaser, which is the same as |
| 766 |
< |
* this Phaser if it has no parent. |
| 765 |
> |
* Returns the root ancestor of this phaser, which is the same as |
| 766 |
> |
* this phaser if it has no parent. |
| 767 |
|
* |
| 768 |
< |
* @return the root ancestor of this Phaser |
| 768 |
> |
* @return the root ancestor of this phaser |
| 769 |
|
*/ |
| 770 |
|
public Phaser getRoot() { |
| 771 |
|
return root; |
| 772 |
|
} |
| 773 |
|
|
| 774 |
|
/** |
| 775 |
< |
* Returns {@code true} if this barrier has been terminated. |
| 775 |
> |
* Returns {@code true} if this phaser has been terminated. |
| 776 |
|
* |
| 777 |
< |
* @return {@code true} if this barrier has been terminated |
| 777 |
> |
* @return {@code true} if this phaser has been terminated |
| 778 |
|
*/ |
| 779 |
|
public boolean isTerminated() { |
| 780 |
|
return root.state < 0L; |
| 783 |
|
/** |
| 784 |
|
* Overridable method to perform an action upon impending phase |
| 785 |
|
* advance, and to control termination. This method is invoked |
| 786 |
< |
* upon arrival of the party tripping the barrier (when all other |
| 786 |
> |
* upon arrival of the party advancing this phaser (when all other |
| 787 |
|
* waiting parties are dormant). If this method returns {@code |
| 788 |
< |
* true}, then, rather than advance the phase number, this barrier |
| 788 |
> |
* true}, then, rather than advance the phase number, this phaser |
| 789 |
|
* will be set to a final termination state, and subsequent calls |
| 790 |
|
* to {@link #isTerminated} will return true. Any (unchecked) |
| 791 |
|
* Exception or Error thrown by an invocation of this method is |
| 792 |
< |
* propagated to the party attempting to trip the barrier, in |
| 792 |
> |
* propagated to the party attempting to advance this phaser, in |
| 793 |
|
* which case no advance occurs. |
| 794 |
|
* |
| 795 |
< |
* <p>The arguments to this method provide the state of the Phaser |
| 795 |
> |
* <p>The arguments to this method provide the state of the phaser |
| 796 |
|
* prevailing for the current transition. The effects of invoking |
| 797 |
< |
* arrival, registration, and waiting methods on this Phaser from |
| 797 |
> |
* arrival, registration, and waiting methods on this phaser from |
| 798 |
|
* within {@code onAdvance} are unspecified and should not be |
| 799 |
|
* relied on. |
| 800 |
|
* |
| 801 |
< |
* <p>If this Phaser is a member of a tiered set of Phasers, then |
| 802 |
< |
* {@code onAdvance} is invoked only for its root Phaser on each |
| 801 |
> |
* <p>If this phaser is a member of a tiered set of phasers, then |
| 802 |
> |
* {@code onAdvance} is invoked only for its root phaser on each |
| 803 |
|
* advance. |
| 804 |
|
* |
| 805 |
|
* <p>To support the most common use cases, the default |
| 815 |
|
* protected boolean onAdvance(int phase, int parties) { return false; } |
| 816 |
|
* }}</pre> |
| 817 |
|
* |
| 818 |
< |
* @param phase the phase number on entering the barrier |
| 818 |
> |
* @param phase the current phase number on entry to this method, |
| 819 |
> |
* before this phaser is advanced |
| 820 |
|
* @param registeredParties the current number of registered parties |
| 821 |
< |
* @return {@code true} if this barrier should terminate |
| 821 |
> |
* @return {@code true} if this phaser should terminate |
| 822 |
|
*/ |
| 823 |
|
protected boolean onAdvance(int phase, int registeredParties) { |
| 824 |
|
return registeredParties == 0; |
| 825 |
|
} |
| 826 |
|
|
| 827 |
|
/** |
| 828 |
< |
* Returns a string identifying this Phaser, as well as its |
| 828 |
> |
* Returns a string identifying this phaser, as well as its |
| 829 |
|
* state. The state, in brackets, includes the String {@code |
| 830 |
|
* "phase = "} followed by the phase number, {@code "parties = "} |
| 831 |
|
* followed by the number of registered parties, and {@code |
| 832 |
|
* "arrived = "} followed by the number of arrived parties. |
| 833 |
|
* |
| 834 |
< |
* @return a string identifying this barrier, as well as its state |
| 834 |
> |
* @return a string identifying this phaser, as well as its state |
| 835 |
|
*/ |
| 836 |
|
public String toString() { |
| 837 |
|
return stateToString(reconcileState()); |
| 853 |
|
* Removes and signals threads from queue for phase. |
| 854 |
|
*/ |
| 855 |
|
private void releaseWaiters(int phase) { |
| 856 |
+ |
QNode q; // first element of queue |
| 857 |
+ |
int p; // its phase |
| 858 |
+ |
Thread t; // its thread |
| 859 |
|
AtomicReference<QNode> head = (phase & 1) == 0 ? evenQ : oddQ; |
| 855 |
– |
QNode q; |
| 856 |
– |
int p; |
| 860 |
|
while ((q = head.get()) != null && |
| 861 |
|
((p = q.phase) == phase || |
| 862 |
|
(int)(root.state >>> PHASE_SHIFT) != p)) { |
| 863 |
< |
if (head.compareAndSet(q, q.next)) |
| 864 |
< |
q.signal(); |
| 863 |
> |
if (head.compareAndSet(q, q.next) && |
| 864 |
> |
(t = q.thread) != null) { |
| 865 |
> |
q.thread = null; |
| 866 |
> |
LockSupport.unpark(t); |
| 867 |
> |
} |
| 868 |
|
} |
| 869 |
|
} |
| 870 |
|
|
| 894 |
|
* @return current phase |
| 895 |
|
*/ |
| 896 |
|
private int internalAwaitAdvance(int phase, QNode node) { |
| 897 |
< |
boolean queued = false; // true when node is enqueued |
| 898 |
< |
int lastUnarrived = -1; // to increase spins upon change |
| 897 |
> |
releaseWaiters(phase-1); // ensure old queue clean |
| 898 |
> |
boolean queued = false; // true when node is enqueued |
| 899 |
> |
int lastUnarrived = 0; // to increase spins upon change |
| 900 |
|
int spins = SPINS_PER_ARRIVAL; |
| 901 |
|
long s; |
| 902 |
|
int p; |
| 903 |
|
while ((p = (int)((s = state) >>> PHASE_SHIFT)) == phase) { |
| 904 |
< |
int unarrived = (int)s & UNARRIVED_MASK; |
| 905 |
< |
if (node != null && node.isReleasable()) { |
| 906 |
< |
p = (int)(state >>> PHASE_SHIFT); |
| 907 |
< |
break; // done or aborted |
| 901 |
< |
} |
| 902 |
< |
else if (node == null && Thread.interrupted()) { |
| 903 |
< |
node = new QNode(this, phase, false, false, 0L); |
| 904 |
< |
node.wasInterrupted = true; |
| 905 |
< |
} |
| 906 |
< |
else if (unarrived != lastUnarrived) { |
| 907 |
< |
if (lastUnarrived == -1) // ensure old queue clean |
| 908 |
< |
releaseWaiters(phase-1); |
| 909 |
< |
if ((lastUnarrived = unarrived) < NCPU) |
| 904 |
> |
if (node == null) { // spinning in noninterruptible mode |
| 905 |
> |
int unarrived = (int)s & UNARRIVED_MASK; |
| 906 |
> |
if (unarrived != lastUnarrived && |
| 907 |
> |
(lastUnarrived = unarrived) < NCPU) |
| 908 |
|
spins += SPINS_PER_ARRIVAL; |
| 909 |
+ |
boolean interrupted = Thread.interrupted(); |
| 910 |
+ |
if (interrupted || --spins < 0) { // need node to record intr |
| 911 |
+ |
node = new QNode(this, phase, false, false, 0L); |
| 912 |
+ |
node.wasInterrupted = interrupted; |
| 913 |
+ |
} |
| 914 |
|
} |
| 915 |
< |
else if (spins > 0) |
| 916 |
< |
--spins; |
| 917 |
< |
else if (node == null) // null if noninterruptible mode |
| 915 |
< |
node = new QNode(this, phase, false, false, 0L); |
| 916 |
< |
else if (!queued) { // push onto queue |
| 915 |
> |
else if (node.isReleasable()) // done or aborted |
| 916 |
> |
break; |
| 917 |
> |
else if (!queued) { // push onto queue |
| 918 |
|
AtomicReference<QNode> head = (phase & 1) == 0 ? evenQ : oddQ; |
| 919 |
< |
QNode q = head.get(); |
| 920 |
< |
if (q == null || q.phase == phase) { |
| 921 |
< |
node.next = q; |
| 921 |
< |
if ((p = (int)(state >>> PHASE_SHIFT)) != phase) |
| 922 |
< |
break; // recheck to avoid stale enqueue |
| 919 |
> |
QNode q = node.next = head.get(); |
| 920 |
> |
if ((q == null || q.phase == phase) && |
| 921 |
> |
(int)(state >>> PHASE_SHIFT) == phase) // avoid stale enq |
| 922 |
|
queued = head.compareAndSet(q, node); |
| 924 |
– |
} |
| 923 |
|
} |
| 924 |
|
else { |
| 925 |
|
try { |
| 932 |
|
|
| 933 |
|
if (node != null) { |
| 934 |
|
if (node.thread != null) |
| 935 |
< |
node.thread = null; // disable unpark() in node.signal |
| 935 |
> |
node.thread = null; // avoid need for unpark() |
| 936 |
|
if (node.wasInterrupted && !node.interruptible) |
| 937 |
|
Thread.currentThread().interrupt(); |
| 938 |
+ |
if ((p = (int)(state >>> PHASE_SHIFT)) == phase) |
| 939 |
+ |
return p; // recheck abort |
| 940 |
|
} |
| 941 |
< |
if (p != phase) |
| 942 |
< |
releaseWaiters(phase); |
| 941 |
> |
releaseWaiters(phase); |
| 942 |
|
return p; |
| 943 |
|
} |
| 944 |
|
|
| 968 |
|
} |
| 969 |
|
|
| 970 |
|
public boolean isReleasable() { |
| 971 |
< |
Thread t = thread; |
| 972 |
< |
if (t != null) { |
| 973 |
< |
if (phaser.getPhase() != phase) |
| 975 |
< |
t = null; |
| 976 |
< |
else { |
| 977 |
< |
if (Thread.interrupted()) |
| 978 |
< |
wasInterrupted = true; |
| 979 |
< |
if (wasInterrupted && interruptible) |
| 980 |
< |
t = null; |
| 981 |
< |
else if (timed) { |
| 982 |
< |
if (nanos > 0) { |
| 983 |
< |
long now = System.nanoTime(); |
| 984 |
< |
nanos -= now - lastTime; |
| 985 |
< |
lastTime = now; |
| 986 |
< |
} |
| 987 |
< |
if (nanos <= 0) |
| 988 |
< |
t = null; |
| 989 |
< |
} |
| 990 |
< |
} |
| 991 |
< |
if (t != null) |
| 992 |
< |
return false; |
| 971 |
> |
if (thread == null) |
| 972 |
> |
return true; |
| 973 |
> |
if (phaser.getPhase() != phase) { |
| 974 |
|
thread = null; |
| 975 |
+ |
return true; |
| 976 |
+ |
} |
| 977 |
+ |
if (Thread.interrupted()) |
| 978 |
+ |
wasInterrupted = true; |
| 979 |
+ |
if (wasInterrupted && interruptible) { |
| 980 |
+ |
thread = null; |
| 981 |
+ |
return true; |
| 982 |
+ |
} |
| 983 |
+ |
if (timed) { |
| 984 |
+ |
if (nanos > 0L) { |
| 985 |
+ |
long now = System.nanoTime(); |
| 986 |
+ |
nanos -= now - lastTime; |
| 987 |
+ |
lastTime = now; |
| 988 |
+ |
} |
| 989 |
+ |
if (nanos <= 0L) { |
| 990 |
+ |
thread = null; |
| 991 |
+ |
return true; |
| 992 |
+ |
} |
| 993 |
|
} |
| 994 |
< |
return true; |
| 994 |
> |
return false; |
| 995 |
|
} |
| 996 |
|
|
| 997 |
|
public boolean block() { |
| 1003 |
|
LockSupport.parkNanos(this, nanos); |
| 1004 |
|
return isReleasable(); |
| 1005 |
|
} |
| 1007 |
– |
|
| 1008 |
– |
void signal() { |
| 1009 |
– |
Thread t = thread; |
| 1010 |
– |
if (t != null) { |
| 1011 |
– |
thread = null; |
| 1012 |
– |
LockSupport.unpark(t); |
| 1013 |
– |
} |
| 1014 |
– |
} |
| 1006 |
|
} |
| 1007 |
|
|
| 1008 |
|
// Unsafe mechanics |
