|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.ObjectEDU.oswego.cs.dl.util.concurrent.Rendezvous
public class Rendezvous
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 restart
ed. 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 |
---|
protected final int parties_
protected boolean broken_
protected int entries_
protected long departures_
protected final Semaphore entryGate_
protected final java.lang.Object[] slots_
protected Rendezvous.RendezvousFunction rendezvousFunction_
Constructor Detail |
---|
public Rendezvous(int parties)
java.lang.IllegalArgumentException
- if parties less than or equal to zero.public Rendezvous(int parties, Rendezvous.RendezvousFunction function)
java.lang.IllegalArgumentException
- if parties less than or equal to zero.Method Detail |
---|
public Rendezvous.RendezvousFunction setRendezvousFunction(Rendezvous.RendezvousFunction function)
function
- the function to run. If null, no function is run.
public int parties()
Barrier
parties
in interface Barrier
public boolean broken()
Barrier
broken
in interface Barrier
public void restart()
public java.lang.Object rendezvous(java.lang.Object x) throws java.lang.InterruptedException, BrokenBarrierException
x
- the item to present at rendezvous point.
By default, this item is exchanged with another.
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
.
java.lang.InterruptedException
- if this thread was interrupted
during the exchange. If so, broken
status is also set.public java.lang.Object attemptRendezvous(java.lang.Object x, long msecs) throws java.lang.InterruptedException, TimeoutException, BrokenBarrierException
x
- the item to present at rendezvous point.
By default, this item is exchanged with another.msecs
- The maximum time to wait.
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
.
java.lang.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.protected java.lang.Object doRendezvous(java.lang.Object x, boolean timed, long msecs) throws java.lang.InterruptedException, TimeoutException, BrokenBarrierException
java.lang.InterruptedException
TimeoutException
BrokenBarrierException
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |