Condition

Condition

java.util.concurrent.locks

---

Java 5.0

This interface defines an alternative to the wait( ) , notify( ) , and notifyAll( ) methods of java.lang.Object . Condition objects are always associated with a corresponding Lock . Obtain a Condition with the newCondition( ) method of Lock .

There are five choices for waiting. The no-argument version of await( ) is the simplest: it blocks until the thread is signaled or interrupted . awaitUninterruptibly( ) blocks until the thread is signaled and ignores interrupts. The other three waiting methods are timed waits: they all wait until signaled, interrupted, or until the specified time elapses. await( ) and awaitUntil( ) return TRue if they are signaled and false if a timeout occurs. awaitNanos( ) specifies the timeout in nanoseconds. It returns zero or a negative number if the timeout elapses. If it wakes up because of a signal (or because of a spurious wakeup ), it returns an estimate of the time remaining in the timeout. If it turns out that the thread needs to continue waiting, this return value can be used as the new timeout value.

The signal( ) and signalAll( ) methods are just like the notify( ) and notifyAll( ) methods of Object . signal( ) wakes up one waiting thread, and signalAll( ) wakes up all waiting threads.

Locking considerations apply to the use of a Condition object just as they apply to the use of the wait( ) and notify( ) methods of Object . Before a thread can call any of the waiting or signaling methods of a Condition , it must hold the Lock associated with the condition. When the thread begins waiting, it automatically relinquishes the Lock , and when it awakes because of a signal, timeout, or interrupt, it must reacquire the lock before it can proceed. A thread is guaranteed to hold the lock when it returns from one of the waiting methods.

Threads waiting on a Condition may wake up spuriously, just as they may when waiting on an Object . Therefore, calls to wait on a Condition are typically written in the form of a loop so that the desired condition is retested when the thread wakes up.

 public interface  Condition  {  // Public Instance Methods  void  await  ( ) throws InterruptedException;        boolean  await  (long  time  , java.util.concurrent.TimeUnit  unit  )          throws InterruptedException;        long  awaitNanos  (long  nanosTimeout  ) throws InterruptedException;        void  awaitUninterruptibly  ( );        boolean  awaitUntil  (java.util.Date  deadline  ) throws InterruptedException;        void  signal  ( );        void  signalAll  ( );   } 

Implementations

AbstractQueuedSynchronizer.ConditionObject

Passed To

ReentrantLock.{getWaitingThreads( ) , getWaitQueueLength( ) , hasWaiters( )} , ReentrantReadWriteLock.{getWaitingThreads( ) , getWaitQueueLength( ) , hasWaiters( )}

Returned By

Lock.newCondition( ) , ReentrantLock.newCondition( ) , ReentrantReadWriteLock.ReadLock.newCondition( ) , ReentrantReadWriteLock.WriteLock.newCondition( )