Java.util.concurrent.Phaser class in Java with Examples

Phaser's primary purpose is to enable synchronization of threads that represent one or more phases of activity. It lets us define a synchronization object that waits until a specific phase has been completed. It then advances to the next phase until that phase concludes. It can also be used to synchronize a single phase, and in that regard, it acts much like a CyclicBarrier.

Class Hierarchy  

java.lang.Object
 ? java.util.concurrent
 ? Class Phaser 

Syntax  

public class Phaser
 extends Object

Constructors: 

• Phaser() - This creates a phaser with initially zero registered parties. A thread can only use this phaser after registering for it.

public Phaser()

• Phaser(int parties) - This creates a phaser that requires parties number of threads to advance to the next phase.

public Phaser(int parties)
throws IllegalArgumentException

• Phaser(Phaser parent) - This specifies a parent phaser for the new object. The number of registered parties is set to zero.

public Phaser(Phaser parent)

• Phaser(Phaser parent, int parties) - This specifies a parent phaser for the newly created object and the number of parties required to advance to the next phase.

public Phaser(Phaser parent, int parties)
throws IllegalArgumentException

Example1: 

Note: Output may vary with each run.  

Starting
Thread: B Phase Zero Started
Thread: A Phase Zero Started
Thread: C Phase Zero Started
Thread: A Phase One Started
Thread: B Phase One Started
Thread: C Phase One Started
Phase 0 Complete
Phase Zero Ended
Phase 1 Complete
Phase One Ended
Thread: C Phase Two Started
Thread: A Phase Two Started
Thread: B Phase Two Started
Phase 2 Complete
Phase Two Ended
Phaser is terminated

Example2: 

Starting
Thread: C Phase Zero Started
Thread: A Phase Zero Started
Thread: B Phase Zero Started
Thread: B Phase One Started
Thread: C Phase One Started
Thread: A Phase One Started
Phase 0 Complete
Phase Zero Ended
Phase 1 Complete
Phase One Ended
Thread: A Phase Two Started
Thread: C Phase Two Started
Thread: B Phase Two Started
Phase 2 Complete
Phase Two Ended
Phaser is terminated

Methods: 

• int register() - This method is used to register parties after a phaser has been constructed. It returns the phase number of the phase to which it is registered.

public int register()
throws IllegalArgumentException

• int arrive() - This method signals that a thread has completed some portion of the task. It does not suspend the execution of the calling thread. It returns the current phase number or a negative value if the phaser has been terminated.

public int arrive()
throws IllegalStateException

• int arriveAndDeregister() - This method enables a thread to arrive at a phase and deregister itself, without waiting for other threads to arrive. It returns the current phase number or a negative value if the phaser has been terminated.

public int arriveAndDeregister()
throws IllegalStateException

• int arriveAndAwaitAdvance() - This method suspends the execution of the thread at a phase, to wait for other threads. It returns the current phase number or a negative value if the phaser has been terminated.

public int arriveAndAwaitAdvance()
throws IllegalStateException

• final int getPhase() - This method returns the current phase number. A negative value is returned if the invoking phasers terminated.

public final int getPhase() 

• boolean onAdvance(int phase, int parties) - This method helps in defining how a phase advancement should occur. To do this, the user must override this method. To terminate the phaser, onAdvance() method returns true, otherwise, it returns false;

protected boolean onAdvance(int phase, int parties)

Example to demonstrate the methods of Phaser class - where the method is overridden so that the phaser executes only a specified number of phases. 

Starting
Thread B Beginning Phase 0
Thread C Beginning Phase 0
Thread A Beginning Phase 0
Phase 0 completed.

Thread A Beginning Phase 1
Thread B Beginning Phase 1
Thread C Beginning Phase 1
Phase 1 completed.

Thread C Beginning Phase 2
Thread A Beginning Phase 2
Thread B Beginning Phase 2
Phase 2 completed.

Thread A Beginning Phase 3
Thread B Beginning Phase 3
Thread C Beginning Phase 3
Phase 3 completed.

The phaser is terminated

Reference: https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Phaser.html