EDU.oswego.cs.dl.util.concurrent

Class Rendezvous

public class Rendezvous extends Object implements Barrier

A rendezvous is a barrier that:

Rendezvous use an all-or-none breakage model for failed synchronization attempts: If threads leave a rendezvous point prematurely because of timeout or interruption, others will also leave abnormally (via BrokenBarrierException), until the rendezvous is restarted. This is usually the simplest and best strategy for sharing knowledge about failures among cooperating threads in the most common usages contexts of Rendezvous.

While any positive number (including 1) of parties can be handled, the most common case is to have two parties.

Sample Usage

Here are the highlights of a class that uses a Rendezvous to swap buffers between threads so that the thread filling the buffer gets a freshly emptied one when it needs it, handing off the filled one to the thread emptying the buffer.

 class FillAndEmpty {
   Rendezvous exchanger = new Rendezvous(2);
   Buffer initialEmptyBuffer = ... a made-up type
   Buffer initialFullBuffer = ...

   class FillingLoop implements Runnable {
     public void run() {
       Buffer currentBuffer = initialEmptyBuffer;
       try {
         while (currentBuffer != null) {
           addToBuffer(currentBuffer);
           if (currentBuffer.full()) 
             currentBuffer = (Buffer)(exchanger.rendezvous(currentBuffer));
         }
       }
       catch (BrokenBarrierException ex) {
         return;
       }
       catch (InterruptedException ex) {
         Thread.currentThread().interrupt();
       }
     }
   }

   class EmptyingLoop implements Runnable {
     public void run() {
       Buffer currentBuffer = initialFullBuffer;
       try {
         while (currentBuffer != null) {
           takeFromBuffer(currentBuffer);
           if (currentBuffer.empty()) 
             currentBuffer = (Buffer)(exchanger.rendezvous(currentBuffer));
         }
       }
       catch (BrokenBarrierException ex) {
         return;
       }
       catch (InterruptedException ex) {
         Thread.currentThread().interrupt();
       }
     }
   }

   void start() {
     new Thread(new FillingLoop()).start();
     new Thread(new EmptyingLoop()).start();
   }
 }
 

[ Introduction to this package. ]

Nested Class Summary
interfaceRendezvous.RendezvousFunction
Interface for functions run at rendezvous points
static classRendezvous.Rotator
The default rendezvous function.
Field Summary
protected booleanbroken_
protected longdepartures_
Number of threads that are permitted to depart rendezvous
protected intentries_
Number of threads that have entered rendezvous
protected SemaphoreentryGate_
Incoming threads pile up on entry until last set done.
protected intparties_
protected Rendezvous.RendezvousFunctionrendezvousFunction_
The function to run at rendezvous point
protected Object[]slots_
Temporary holder for items in exchange
Constructor Summary
Rendezvous(int parties)
Create a Barrier for the indicated number of parties, and the default Rotator function to run at each barrier point.
Rendezvous(int parties, Rendezvous.RendezvousFunction function)
Create a Barrier for the indicated number of parties. and the given function to run at each barrier point.
Method Summary
ObjectattemptRendezvous(Object x, long msecs)
Wait msecs to complete a rendezvous.
booleanbroken()
protected ObjectdoRendezvous(Object x, boolean timed, long msecs)
intparties()
Objectrendezvous(Object x)
Enter a rendezvous; returning after all other parties arrive.
voidrestart()
Reset to initial state.
Rendezvous.RendezvousFunctionsetRendezvousFunction(Rendezvous.RendezvousFunction function)
Set the function to call at the point at which all threads reach the rendezvous.

Field Detail

broken_

protected boolean broken_

departures_

protected long departures_
Number of threads that are permitted to depart rendezvous

entries_

protected int entries_
Number of threads that have entered rendezvous

entryGate_

protected final Semaphore entryGate_
Incoming threads pile up on entry until last set done.

parties_

protected final int parties_

rendezvousFunction_

protected Rendezvous.RendezvousFunction rendezvousFunction_
The function to run at rendezvous point

slots_

protected final Object[] slots_
Temporary holder for items in exchange

Constructor Detail

Rendezvous

public Rendezvous(int parties)
Create a Barrier for the indicated number of parties, and the default Rotator function to run at each barrier point.

Throws: IllegalArgumentException if parties less than or equal to zero.

Rendezvous

public Rendezvous(int parties, Rendezvous.RendezvousFunction function)
Create a Barrier for the indicated number of parties. and the given function to run at each barrier point.

Throws: IllegalArgumentException if parties less than or equal to zero.

Method Detail

attemptRendezvous

public Object attemptRendezvous(Object x, long msecs)
Wait msecs to complete a rendezvous.

Parameters: x the item to present at rendezvous point. By default, this item is exchanged with another. msecs The maximum time to wait.

Returns: an item x given by some thread, and/or processed by the rendezvousFunction.

Throws: BrokenBarrierException if any other thread in any previous or current barrier since either creation or the last restart operation left the barrier prematurely due to interruption or time-out. (If so, the broken status is also set.) Also returns as broken if the RendezvousFunction encountered a run-time exception. Threads that are noticed to have been interrupted after being released are not considered to have broken the barrier. In all cases, the interruption status of the current thread is preserved, so can be tested by checking Thread.interrupted. InterruptedException if this thread was interrupted during the exchange. If so, broken status is also set. TimeoutException if this thread timed out waiting for the exchange. If the timeout occured while already in the exchange, broken status is also set.

broken

public boolean broken()

doRendezvous

protected Object doRendezvous(Object x, boolean timed, long msecs)

parties

public int parties()

rendezvous

public Object rendezvous(Object x)
Enter a rendezvous; returning after all other parties arrive.

Parameters: x the item to present at rendezvous point. By default, this item is exchanged with another.

Returns: an item x given by some thread, and/or processed by the rendezvousFunction.

Throws: BrokenBarrierException if any other thread in any previous or current barrier since either creation or the last restart operation left the barrier prematurely due to interruption or time-out. (If so, the broken status is also set.) Also returns as broken if the RendezvousFunction encountered a run-time exception. Threads that are noticed to have been interrupted after being released are not considered to have broken the barrier. In all cases, the interruption status of the current thread is preserved, so can be tested by checking Thread.interrupted. InterruptedException if this thread was interrupted during the exchange. If so, broken status is also set.

restart

public void restart()
Reset to initial state. Clears both the broken status and any record of waiting threads, and releases all currently waiting threads with indeterminate return status. This method is intended only for use in recovery actions in which it is somehow known that no thread could possibly be relying on the the synchronization properties of this barrier.

setRendezvousFunction

public Rendezvous.RendezvousFunction setRendezvousFunction(Rendezvous.RendezvousFunction function)
Set the function to call at the point at which all threads reach the rendezvous. This function is run exactly once, by the thread that trips the barrier. The function is not run if the barrier is broken.

Parameters: function the function to run. If null, no function is run.

Returns: the previous function