org.multiverse.commitbarriers
Class CountDownCommitBarrier

java.lang.Object
  org.multiverse.commitbarriers.CommitBarrier
      org.multiverse.commitbarriers.CountDownCommitBarrier

public final class CountDownCommitBarrier
extends CommitBarrier

A synchronization aid that allows a set of threads and transaction to all wait for each other to reach a common barrier point; once this barrier is opened, all transaction atomically commit. A CountDownCommitBarrier is useful in programs involving a fixed sized party of threads/transactions that must occasionally wait for each other.

The CountDownCommitBarrier looks a lot like the CountDownLatch. So if you have experience with that functionality, this one should feel familiar.

A CountDownCommitBarrier is initialized with a given count. The CommitBarrier.joinCommit(org.multiverse.api.Txn) await} methods block until the current count reaches zero due to invocations of the countDown() method, after which all waiting threads are released. Unlike the CountDownLatch, it isn't allowed for a new transaction to call one of the join methods after the barrier has aborted or committed.

This functionality is useful for two phase commit related functionality.

The CountDownCommitBarrier can't be reused, so it is not cyclic like the CyclicBarrier.

A CountDownCommitBarrier is thread-safe to use of course.

Author:

Peter Veentjer.

See Also:

VetoCommitBarrier

Field Summary

Fields inherited from class org.multiverse.commitbarriers.CommitBarrier

lock, statusCondition

Constructor Summary

CountDownCommitBarrier(int parties)
Create a new CountDownCommitBarrier that uses an unfair lock.

CountDownCommitBarrier(int parties, boolean fair)
Creates a new CountDownCommitBarrier.

Method Summary

void	atomicIncParties() Adds 1 additional party to this CountDownCommitBarrier.
void	atomicIncParties(int extra) Atomically adds additional parties to this CountDownCommitBarrier.
void	countDown() Signal that one party has returned.
int	getParties() Returns the number of parties that want to join this CountDownCommitBarrier.
void	incParties(Txn tx, int extra) Increases the number of parties that need to return before this CommitBarrier can open.
protected boolean	isLastParty()

Methods inherited from class org.multiverse.commitbarriers.CommitBarrier

abort, addJoiner, awaitOpen, awaitOpenUninterruptibly, ensureNotDead, executeTasks, finish, getNumberWaiting, getStatus, isAborted, isClosed, isCommitted, joinCommit, joinCommitUninterruptibly, registerOnAbortTask, registerOnCommitTask, setScheduledExecutorService, setTimeout, signalAborted, signalCommit, tryAwaitOpen, tryAwaitOpenUninterruptibly, tryJoinCommit, tryJoinCommit, tryJoinCommitUninterruptibly

Methods inherited from class java.lang.Object

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

Constructor Detail

CountDownCommitBarrier

public CountDownCommitBarrier(int parties)

Create a new CountDownCommitBarrier that uses an unfair lock.

Parameters:

parties - the number of parties waiting. If the number of parties is 0, the VetoCommitBarrier is created committed, else it will be closed.

Throws:

IllegalArgumentException - if parties is smaller than 0.

CountDownCommitBarrier

public CountDownCommitBarrier(int parties,
                              boolean fair)

Creates a new CountDownCommitBarrier.

Parameters:

parties - the number of parties waiting. If the number of parties is 0, the VetoCommitBarrier is created committed, else it will be closed.

fair - if the lock bu this CountDownCommitBarrier is fair.

Throws:

IllegalArgumentException - if parties smaller than 0.

Method Detail

getParties

public int getParties()

Returns the number of parties that want to join this CountDownCommitBarrier.

Returns:

the number of parties.

isLastParty

protected boolean isLastParty()

Specified by:

isLastParty in class CommitBarrier

countDown

public void countDown()

Signal that one party has returned. If this is the last party to returned, all transactions will commit.

If the all parties already have returned, this call is ignored. This is the same behavior as the CountDownLatch.countDown() method provides.

atomicIncParties

public void atomicIncParties()

Adds 1 additional party to this CountDownCommitBarrier.

Throws:

CommitBarrierOpenException - if this CountDownCommitBarrier already is committed or aborted.

See Also:

atomicIncParties(int)

atomicIncParties

public void atomicIncParties(int extra)

Atomically adds additional parties to this CountDownCommitBarrier.

Call is ignored when extra is 0.

This method is not transactional, so be very careful calling it within a transaction. Transactions can be retried, so this method could be called more than once. This means that the number of added parties could be completely bogus. For a transactional version see incParties(org.multiverse.api.Txn, int).

Parameters:

extra - the additional parties.

Throws:

IllegalArgumentException - if extra smaller than 0.

CommitBarrierOpenException - if this CountDownCommitBarrier already is open.

incParties

public void incParties(Txn tx,
                       int extra)

Increases the number of parties that need to return before this CommitBarrier can open. The parties are only increased after the transaction has committed.

If extra is 0, this call is ignored (unless the Txn is not active, then a IllegalTransactionState will be thrown.

This is the call you want to use when you are doing an atomicIncParties inside a transaction. A transaction can be retried multiple times, and if number of parties is incremented more than once, you run into problems. That is why a transaction can be passed where a compensating tasks is registered on, that removes the added parties when the transaction is aborted.

Parameters:

tx - the transaction where this operation lifts on.

extra - the number of extra parties

Throws:

NullPointerException - if tx is null.

IllegalArgumentException - is extra smaller than zero.

IllegalTxnStateException - if the transaction is not in the correct state for this operation (so not active).