EDU.oswego.cs.dl.util.concurrent
public class Rendezvous extends Object implements Barrier
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(); } }
Nested Class Summary | |
---|---|
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 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 | |
---|---|
Object | attemptRendezvous(Object x, long msecs)
Wait msecs to complete a rendezvous. |
boolean | broken() |
protected Object | doRendezvous(Object x, boolean timed, long msecs) |
int | parties() |
Object | rendezvous(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. |
Throws: IllegalArgumentException if parties less than or equal to zero.
Throws: IllegalArgumentException if parties less than or equal to zero.
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.
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.
Parameters: function the function to run. If null, no function is run.
Returns: the previous function