Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

CountDownLatch Class Reference

A synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes. More...

List of all members.

Public Member Functions

 this (int count)
void wait ()
bool wait (long timeout, TimeUnit unit)
void countDown ()
long count ()
char[] toString ()

Private Attributes

Sync sync

Classes

class  Sync


Detailed Description

A synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes.

A CountDownLatch is initialized with a given count. The wait methods block until the current count reaches zero due to invocations of the countDown method, after which all waiting threads are released and any subsequent invocations of wait return immediately. This is a one-shot phenomenon -- the count cannot be reset. If you need a version that resets the count, consider using a CyclicBarrier.

A CountDownLatch is a versatile synchronization tool and can be used for a number of purposes. A CountDownLatch initialized with a count of one serves as a simple on/off latch, or gate: all threads invoking wait wait at the gate until it is opened by a thread invoking countDown. A CountDownLatch initialized to N can be used to make one thread wait until N threads have completed some action, or some action has been completed N times.

A useful property of a CountDownLatch is that it doesn't require that threads calling countDown wait for the count to reach zero before proceeding, it simply prevents any thread from proceeding past an wait until all threads could pass.

Sample usage: Here is a pair of classes in which a group of worker threads use two countdown latches:

 class Driver {
   void main() {
     CountDownLatch startSignal;
     CountDownLatch doneSignal;

     this() {
       startSignal = new CountDownLatch(1);
       doneSignal = new CountDownLatch(N);
     }
     for (int i = 0; i < N; ++i) { // create and start threads
       Worker work = new Worker(startSignal, doneSignal);
       new Thread(&work.run).start();

     doSomethingElse();            // don't let run yet
     startSignal.countDown();      // let all threads proceed
     doSomethingElse();
     doneSignal.wait();            // wait for all to finish
   }
 }

 class Worker {
   private CountDownLatch startSignal;
   private CountDownLatch doneSignal;
   this(CountDownLatch startSignal, CountDownLatch doneSignal) {
      this.startSignal = startSignal;
      this.doneSignal = doneSignal;
   }
   int run() {
      startSignal.wait();
      doWork();
      doneSignal.countDown();
      return 0;
   }

   void doWork() { ... }
 }
 *

Definition at line 99 of file Countdown.d.


Member Function Documentation

this int  count  )  [inline]
 

Constructs a CountDownLatch initialized with the given count.

Parameters:
count the number of times countDown must be invoked before threads can pass through wait

Definition at line 140 of file Countdown.d.

References count().

void wait  )  [inline]
 

Causes the current thread to wait until the latch has counted down to zero.

If the current count is zero then this method returns immediately. If the current count is greater than zero then the current thread becomes disabled for thread scheduling purposes and lies dormant until the count reaches zero due to invocations of the countDown method.

Definition at line 156 of file Countdown.d.

References AbstractLock::acquireShared(), and sync.

bool wait long  timeout,
TimeUnit  unit
[inline]
 

Causes the current thread to wait until the latch has counted down to zero.

If the current count is zero then this method returns immediately with the value true.

If the current count is greater than zero then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happen:

  • The count reaches zero due to invocations of the countDown method; or
  • The specified waiting time elapses.

If the count reaches zero then the method returns with the value true.

If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.

Parameters:
timeout the maximum time to wait
unit the time unit of the timeout argument.
Returns:
true if the count reached zero and false if the waiting time elapsed before the count reached zero.

Definition at line 186 of file Countdown.d.

References sync, toNanos(), and AbstractLock::tryAcquireSharedNanos().

void countDown  )  [inline]
 

Decrements the count of the latch, releasing all waiting threads if the count reaches zero.

If the current count is greater than zero then it is decremented. If the new count is zero then all waiting threads are re-enabled for thread scheduling purposes.

If the current count equals zero then nothing happens.

Definition at line 200 of file Countdown.d.

References AbstractLock::releaseShared(), and sync.

long count  )  [inline]
 

Returns the current count. This method is typically used for debugging and testing purposes.

Returns:
the current count.

Definition at line 209 of file Countdown.d.

References CountDownLatch::Sync::getCount(), and sync.

Referenced by this().

char [] toString  )  [inline]
 

Returns a string identifying this latch, as well as its state. The state, in brackets, includes the String "Count =" followed by the current count.

Returns:
a string identifying this latch, as well as its state

Definition at line 219 of file Countdown.d.

References CountDownLatch::Sync::getCount(), and sync.


Member Data Documentation

Sync sync [private]
 

Definition at line 131 of file Countdown.d.

Referenced by count(), countDown(), toString(), and wait().


The documentation for this class was generated from the following file:
Generated on Sat Dec 24 17:28:38 2005 for Mango by  doxygen 1.4.0