Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> ematgine >> utils >> [ concurrent overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.ematgine.utils.concurrent
Class Rendezvous  

java.lang.Object
  org.ematgine.utils.concurrent.Rendezvous

All Implemented Interfaces:

Barrier

---

public class Rendezvous

extends java.lang.Object

implements Barrier

A rendezvous is a barrier that:

• Unlike a CyclicBarrier, is not restricted to use with fixed-sized groups of threads. Any number of threads can attempt to enter a rendezvous, but only the predetermined number of parties enter and later become released from the rendezvous at any give time.
• Enables each participating thread to exchange information with others at the rendezvous point. Each entering thread presents some object on entry to the rendezvous, and returns some object on release. The object returned is the result of a RendezvousFunction that is run once per rendezvous, (it is run by the last-entering thread). By default, the function applied is a rotation, so each thread returns the object given by the next (modulo parties) entering thread. This default function faciliates simple application of a common use of rendezvous, as exchangers.

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
static interface	Rendezvous.RendezvousFunction           Interface for functions run at rendezvous points
static class	Rendezvous.Rotator           The default rendezvous function.

 

Field Summary
protected  boolean	broken_
protected  long	departures_           Number of threads that are permitted to depart rendezvous
protected  int	entries_           Number of threads that have entered rendezvous
protected  Semaphore	entryGate_           Incoming threads pile up on entry until last set done.
protected  int	parties_
protected  Rendezvous.RendezvousFunction	rendezvousFunction_           The function to run at rendezvous point
protected  java.lang.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.

 

Method Summary
java.lang.Object	attemptRendezvous(java.lang.Object x, long msecs)           Wait msecs to complete a rendezvous.
boolean	broken()           Returns true if the barrier has been compromised by threads leaving the barrier before a synchronization point (normally due to interruption or timeout).
protected  java.lang.Object	doRendezvous(java.lang.Object x, boolean timed, long msecs)
int	parties()           Return the number of parties that must meet per barrier point.
java.lang.Object	rendezvous(java.lang.Object x)           Enter a rendezvous; returning after all other parties arrive.
void	restart()           Reset to initial state.
Rendezvous.RendezvousFunction	setRendezvousFunction(Rendezvous.RendezvousFunction function)           Set the function to call at the point at which all threads reach the rendezvous.

 

Methods inherited from class java.lang.Object

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

 

Field Detail

parties_

protected final int parties_

---

broken_

protected boolean broken_

---

entries_

protected int entries_

Number of threads that have entered rendezvous

---

departures_

protected long departures_

Number of threads that are permitted to depart rendezvous

---

entryGate_

protected final Semaphore entryGate_

Incoming threads pile up on entry until last set done.

---

slots_

protected final java.lang.Object[] slots_

Temporary holder for items in exchange

---

rendezvousFunction_

protected Rendezvous.RendezvousFunction rendezvousFunction_

The function to run at rendezvous point

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.

---

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.

Method Detail

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.

---

parties

public int parties()

Description copied from interface: Barrier

Return the number of parties that must meet per barrier point. The number of parties is always at least 1.

Specified by:

parties in interface Barrier

---

broken

public boolean broken()

Description copied from interface: Barrier

Returns true if the barrier has been compromised by threads leaving the barrier before a synchronization point (normally due to interruption or timeout). Barrier methods in implementation classes throw throw BrokenBarrierException upon detection of breakage. Implementations may also support some means to clear this status.

Specified by:

broken in interface Barrier

---

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.

---

rendezvous

public java.lang.Object rendezvous(java.lang.Object x)
                            throws java.lang.InterruptedException,
                                   BrokenBarrierException

Enter a rendezvous; returning after all other parties arrive.

---

attemptRendezvous

public java.lang.Object attemptRendezvous(java.lang.Object x,
                                          long msecs)
                                   throws java.lang.InterruptedException,
                                          TimeoutException,
                                          BrokenBarrierException

Wait msecs to complete a rendezvous.

---

doRendezvous

protected java.lang.Object doRendezvous(java.lang.Object x,
                                        boolean timed,
                                        long msecs)
                                 throws java.lang.InterruptedException,
                                        TimeoutException,
                                        BrokenBarrierException

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> ematgine >> utils >> [ concurrent overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---