org.gridgain.grid.util.snaptree

Class Epoch

java.lang.Object

org.gridgain.grid.util.snaptree.Epoch

public abstract class Epoch
extends Object

A Epoch has a lifecycle consisting of three phases: active, closing, and closed. During the active phase partipants may arrive and leave the epoch. Once a close has been requested, new participants are not allowed, only leaving is possible. Once close has been requested and all participants have left, the epoch is transitioned to the closed state.

Entry is performed with attemptArrive(), which returns a non-null ticket on success or null if beginClose() has already been called. Each successful call to attemptArrive must be paired by a call to Epoch.Ticket.leave(int) on the returned ticket.

The abstract method onClosed(int) will be invoked exactly once after the epoch becomes closed. It will be passed the sum of the values passed to Epoch.Ticket.leave(int). There is no way to query the current participant count or state of the epoch without changing it.

Internally the epoch responds to contention by increasing its size, striping the participant count across multiple objects (and hopefully multiple cache lines). Once close has begun, the epoch converts itself to a single-shot hierarchical barrier, that also performs a hierarchical reduction of the leave parameters.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Epoch.Ticket Represents a single successful arrival to an Epoch.

Constructor Summary

Constructors

Constructor and Description
Epoch()

Method Summary

Methods

Modifier and Type	Method and Description
Epoch.Ticket	attemptArrive() Returns a Epoch.Ticket indicating a successful arrival, if no call to beginClose() has been made for this epoch, or returns null if close has already begun.
void	beginClose() Prevents new arrivals from succeeding, then returns immediately.
protected abstract void	onClosed(int dataSum) Override this method to provide user-defined behavior.

Methods inherited from class java.lang.Object

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

Constructor Detail

Epoch

public Epoch()

Method Detail

attemptArrive

public Epoch.Ticket attemptArrive()

Returns a Epoch.Ticket indicating a successful arrival, if no call to beginClose() has been made for this epoch, or returns null if close has already begun. Epoch.Ticket.leave(int) must be called exactly once on any returned ticket.

beginClose

public void beginClose()

Prevents new arrivals from succeeding, then returns immediately. onClosed(int) will be called after all outstanding tickets have been returned. To block until close is complete, add some sort of synchronization logic to the user-defined implementation of onClosed(int).

onClosed

protected abstract void onClosed(int dataSum)

Override this method to provide user-defined behavior. dataSum will be the sum of the data values passed to Epoch.Ticket.leave(int) for all tickets in this epoch.

As a simple example, a blocking close operation may be defined by:

    class BlockingEpoch extends Epoch {
        private final CountDownLatch _closed = new CountDownLatch(1);

        public void blockingClose() throws InterruptedException {
            beginClose();
            _closed.await();
        }

        protected void onClosed(int dataSum) {
            _closed.countDown(1);
        }
    }