org.apache.ignite.internal.util.snaptree

## Class Epoch

- java.lang.Object
- - org.apache.ignite.internal.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
`static interface` `Epoch.Ticket` Represents a single successful arrival to an `Epoch`.

### Constructor Summary

Constructors
Constructor and Description
`Epoch()`

### Method Summary

Methods
`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);
            }
        }

2017 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 2.2.0
Release Date | : September 15 2017