Class Rendezvous
- All Implemented Interfaces:
Barrier
- 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 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
Nested ClassesModifier and TypeClassDescriptionstatic interface
Interface for functions run at rendezvous pointsstatic class
The default rendezvous function. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected boolean
protected long
Number of threads that are permitted to depart rendezvousprotected int
Number of threads that have entered rendezvousprotected final Semaphore
Incoming threads pile up on entry until last set done.protected final int
protected Rendezvous.RendezvousFunction
The function to run at rendezvous pointprotected final Object[]
Temporary holder for items in exchange -
Constructor Summary
ConstructorsConstructorDescriptionRendezvous
(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
Modifier and TypeMethodDescriptionattemptRendezvous
(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 Object
doRendezvous
(Object x, boolean timed, long msecs) int
parties()
Return the number of parties that must meet per barrier point.rendezvous
(Object x) Enter a rendezvous; returning after all other parties arrive.void
restart()
Reset to initial state.Set the function to call at the point at which all threads reach the rendezvous.
-
Field Details
-
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_
Incoming threads pile up on entry until last set done. -
slots_
Temporary holder for items in exchange -
rendezvousFunction_
The function to run at rendezvous point
-
-
Constructor Details
-
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
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 Details
-
setRendezvousFunction
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
-
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. -
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. -
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
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 lastrestart
operation left the barrier prematurely due to interruption or time-out. (If so, thebroken
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 checkingThread.interrupted
.InterruptedException
- if this thread was interrupted during the exchange. If so,broken
status is also set.
-
attemptRendezvous
public Object attemptRendezvous(Object x, long msecs) throws InterruptedException, TimeoutException, BrokenBarrierException 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 lastrestart
operation left the barrier prematurely due to interruption or time-out. (If so, thebroken
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 checkingThread.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.
-
doRendezvous
protected Object doRendezvous(Object x, boolean timed, long msecs) throws InterruptedException, TimeoutException, BrokenBarrierException
-