jsr166z.forkjoin
Class TaskBarrier

java.lang.Object
  extended by jsr166z.forkjoin.TaskBarrier

public class TaskBarrier
extends java.lang.Object

A synchronization barrier for ForkJoinTasks. A TaskBarrier is similar in functionality to a CyclicBarrier, but differs in the following ways.

  1. The number of parties may vary over time. A task may register to be a party in a barrier at any time (but almost always before being forked), and may deregister upon arriving at the barrier. As is the case with most other basic synchronization constructs, registration and deregistration affect only internal counts; they do not establish any further internal bookkeeping.
  2. TaskBarriers support split-phase operation: The two aspects of coordination, arriving at a barrier (arrive) and awaiting others (awaitCycleAdvance) are independently supported. Like a CyclicBarrier, A TaskBarrier may be repeatedly awaited. Each cycle has an associated value, returned from arrive, that be used as an argument to awaitCycleAdvance. Method arriveAndAwait conveniently combines these. (In descriptions below, a task is termed "active" unless it has arrived at a barrier but has not advanced via awaitCycleAdvance, or has deregistered.)
  3. TaskBarriers may enter a termination state in which all await actions immediately return, indicating (via a negative cycle value) that execution is complete. Termination is triggered by executing the overridable terminate method that is executed each time the barrier is tripped.
  4. TaskBarriers may be used only by ForkJoinTasks. Coordination operations (arriveAndAwait and awaitCycleAdvance) need not block, but instead help other tasks make progress. While not dynamically enforced, only registered tasks may invoke methods arrive, arriveAndAwait, and arriveAndDeregister. However any ForkJoinTask may invoke awaitCycleAdvance. And any caller may invoke status methods such as getParties for the sake of monitoring and debugging.

A TaskBarrier may be used to support a style of programming in which a task waits for others to complete, without otherwise needing to keep track of which tasks it is waiting for. This is similar to the "sync" construct in Cilk and "clocks" in X10. Special constructions based on such barriers are available using the LinkedAsyncAction and CyclicAction classes, but they can be useful in other contexts as well. For a simple (but not very useful) example, here is a variant of Fibonacci:

 class BarrierFibonacci extends RecursiveAction {
   int argument, result;
   final TaskBarrier parentBarrier;
   BarrierFibonacci(int n, TaskBarrier parentBarrier) {
     this.argument = n;
     this.parentBarrier = parentBarrier;
     parentBarrier.register();
   }
   protected void compute() {
     int n = argument;
     if (n <= 1)
        result = n;
     else {
        TaskBarrier childBarrier = new TaskBarrier(1);
        Fibonacci f1 = new Fibonacci(n - 1, childBarrier);
        Fibonacci f2 = new Fibonacci(n - 2, childBarrier);
        f1.fork();
        f2.fork();
        childBarrier.arriveAndAwait();
        result = f1.result + f2.result;
     }
     parentBarrier.arriveAndDeregister();
   }
 }
 

Implementation notes: This implementation restricts the maximum number of registered parties to 65535. Attempts to register additional parties result in IllegalStateExceptions.


Constructor Summary
TaskBarrier()
          Creates a new barrier without any initially registered parties.
TaskBarrier(int parties)
          Creates a new barrier with the given numbers of registered active parties.
 
Method Summary
 int arrive()
          Arrives at the barrier, but does not wait for others.
 int arriveAndAwait()
          Arrives at the barrier and awaits others.
 int arriveAndDeregister()
          Arrives at the barrier, and deregisters from it.
 int awaitCycleAdvance(int cycle)
          Awaits the cycle of the barrier to advance from the given value, by helping other tasks.
 int getActiveParties()
          Returns the number of parties that have not yet arrived at the current cycle of this barrier.
 int getCycle()
          Returns the current cycle number.
 int getRegisteredParties()
          Returns the number of parties registered at this barrier.
 boolean isTerminated()
          Returns true if this barrier has been terminated
 int register()
          Adds a new active party to the barrier.
protected  boolean terminate(int cycle, int registeredParties)
          Overridable method to control termination.
 java.lang.String toString()
          Returns a string identifying this barrier, as well as its state.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TaskBarrier

public TaskBarrier()
Creates a new barrier without any initially registered parties.


TaskBarrier

public TaskBarrier(int parties)
Creates a new barrier with the given numbers of registered active parties.

Parameters:
parties - the number of parties required to trip barrier.
Throws:
java.lang.IllegalArgumentException - if parties less than zero or greater than the maximum number of parties supported.
Method Detail

register

public int register()
Adds a new active party to the barrier.

Returns:
the current barrier cycle number upon registration

arrive

public int arrive()
Arrives at the barrier, but does not wait for others. (You can in turn wait for others via awaitCycleAdvance(int)).

Returns:
the current barrier cycle number upon entry to this method, or a negative value if terminated;

arriveAndDeregister

public int arriveAndDeregister()
Arrives at the barrier, and deregisters from it.

Returns:
the current barrier cycle number upon entry to this method, or a negative value if terminated;

awaitCycleAdvance

public int awaitCycleAdvance(int cycle)
Awaits the cycle of the barrier to advance from the given value, by helping other tasks.

Parameters:
cycle - the cycle on entry to this method
Returns:
the cycle on exit from this method

arriveAndAwait

public int arriveAndAwait()
Arrives at the barrier and awaits others. Unlike other arrival methods, this method returns the arrival index of the caller. The caller tripping the barrier returns zero, the previous caller 1, and so on. This enables creation of barrier actions by the task tripping the barrier using constructions of the form: if (b.arriveAndAwait()== 0) action(); b.arriveAndAwait();

Returns:
the arrival index

getCycle

public int getCycle()
Returns the current cycle number. The maximum cycle number is Integer.MAX_VALUE, after which it restarts at zero. Upon termination, the cycle number is negative.

Returns:
the cycle number, or a negative value if terminated

getRegisteredParties

public int getRegisteredParties()
Returns the number of parties registered at this barrier.

Returns:
the number of parties

getActiveParties

public int getActiveParties()
Returns the number of parties that have not yet arrived at the current cycle of this barrier.

Returns:
the number of active parties

isTerminated

public boolean isTerminated()
Returns true if this barrier has been terminated

Returns:
true if this barrier has been terminated

terminate

protected boolean terminate(int cycle,
                            int registeredParties)
Overridable method to control termination. This method is invoked whenever the barrier is tripped. If it returns true, then this barrier is set to a final termination state, and subsequent calls to getCycle and related methods return negative values.

The default version returns true only when the number of registered parties is zero.

Parameters:
cycle - the cycle count on entering the barrier
registeredParties - the current number of registered parties.

toString

public java.lang.String toString()
Returns a string identifying this barrier, as well as its state. The state, in brackets, includes the String "Cycle =" followed by the cycle number, "parties =" followed by the number of registered parties, and "acivie =" followed by the number of active parties

Overrides:
toString in class java.lang.Object
Returns:
a string identifying this barrier, as well as its state