com.liferay.portal.kernel.concurrent

Class CompeteLatch

java.lang.Object

com.liferay.portal.kernel.concurrent.CompeteLatch

public class CompeteLatch
extends java.lang.Object

A synchronizer based on the JDK's AQS framework to simulate a single winner competition. This synchronizer supports cyclical competition. In this situation, loser threads should try again. The single winner thread will lock the latch while other threads will block on the latch by calling await. After the winner thread finishes its job, it should call done which will open the latch. All blocking loser threads can pass the latch at the same time.

See LPS-3744 for a sample use case.

Author:

Shuyang Zhou

Constructor Summary

Constructors

Constructor and Description
CompeteLatch()

Method Summary

Modifier and Type	Method and Description
void	await() This method should only be called by a loser thread.
boolean	await(long timeout, java.util.concurrent.TimeUnit timeUnit) This method should only be called by a loser thread.
boolean	compete() Tells the current thread to join the competition.
boolean	done() This method should only be called by the winner thread.
boolean	isLocked() Returns true if the latch is locked.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CompeteLatch

public CompeteLatch()

Method Detail

await

public void await()
           throws java.lang.InterruptedException

This method should only be called by a loser thread. If the latch is locked, that means the winner is executing its job and all loser threads that call this method will be blocked. If the latch is not locked, that means the winner has finished its job and all the loser threads calling this method will return immediately. If the winner thread calls this method before his job completed, then all threads will deadlock.

Throws:

java.lang.InterruptedException - if the current thread is interrupted

await

public boolean await(long timeout,
                     java.util.concurrent.TimeUnit timeUnit)
              throws java.lang.InterruptedException

This method should only be called by a loser thread. If the latch is locked, that means the winner is executing its job and all loser threads that call this method will be blocked for the given waiting time. If the latch is not locked, that means the winner has finished its job and all the loser threads calling this method will return immediately. If the winner thread calls this method before his job completed, then all threads will deadlock.

Parameters:

timeout - the timeout value

timeUnit - the time unit

Returns:

true if the latch was open, false if the waiting time elapsed before the latch be opened.

Throws:

java.lang.InterruptedException - if the current thread is interrupted

compete

public boolean compete()

Tells the current thread to join the competition. Return immediately whether or not the current thread is the winner thread or a loser thread. No matter how many threads join this competition, only one thread can be the winner thread.

Returns:

true if the current thread is the winner thread

done

public boolean done()

This method should only be called by the winner thread. The winner thread calls this method to indicate that it has finished its job and unlocks the latch to allow all loser threads return from the await method. If a loser thread does call this method when a winner thread has locked the latch, the latch will break and the winner thread may be put into a non thread safe state. You should never have to do this except to get out of a deadlock. If no one threads have locked the latch, then calling this method has no effect. This method will return immediately.

Returns:

true if this call opens the latch, false if the latch is already open

isLocked

public boolean isLocked()

Returns true if the latch is locked. This method should not be used to test the latch before joining a competition because it is not thread safe. The only purpose for this method is to give external systems a way to monitor the latch which is usually be used for deadlock detection.

Returns:

true if the latch is locked; false otherwise