org.apache.ignite.internal.util.snaptree

## Class CopyOnWriteManager<E>

- java.lang.Object
- - org.apache.ignite.internal.util.snaptree.CopyOnWriteManager<E>

All Implemented Interfaces:
  Cloneable

    public abstract class CopyOnWriteManager<E>
    extends Object
    implements Cloneable

Manages copy-on-write behavior for a concurrent tree structure. It is assumed that the managed structure allows concurrent mutation, but that no mutating operations may be active when a copy-on-write snapshot of tree is taken. Because it is difficult to update the size of data structure in a highly concurrent fashion, the `CopyOnWriteManager` also manages a running total that represents the size of the contained tree structure.

Users should implement the `freezeAndClone(Object)` and `cloneFrozen(Object)` methods.

### Constructor Summary

Constructors
Constructor and Description
`CopyOnWriteManager(E initialValue, int initialSize)` Creates a new `CopyOnWriteManager` holding `initialValue`, with an assumed size of `initialSize`.

### Method Summary

Methods
`E` `availableFrozen()` Returns a reference to a snapshot of this instance's tree structure, if one is available without requiring any additional copying, otherwise returns null.
`Epoch.Ticket` `beginMutation()` Obtains permission to mutate the copy-on-write value held by this instance, perhaps blocking while a concurrent snapshot is being performed.
`Epoch.Ticket` `beginQuiescent()`
`CopyOnWriteManager<E>` `clone()`
`protected abstract E` `cloneFrozen(E frozenValue)` Returns a clone of a frozen E.
`protected abstract E` `freezeAndClone(E value)` The implementing method must mark `value` as shared, and return a new object to use in its place.
`E` `frozen()` Returns a reference to a snapshot of this instance's tree structure that may be read, but not written.
`boolean` `isEmpty()` Returns true if the computed `size()` is zero.
`E` `mutable()` Returns a reference to the tree structure suitable for a mutating operation.
`E` `read()` Returns a reference to the tree structure suitable for a read operation.
`int` `size()` Returns the sum of the `initialSize` parameter passed to the constructor, and the size deltas passed to `Epoch.Ticket.leave(int)` for all of the mutation tickets.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### CopyOnWriteManager

    public CopyOnWriteManager(E initialValue,
                      int initialSize)

Creates a new `CopyOnWriteManager` holding `initialValue`, with an assumed size of `initialSize`.

### Method Detail

#### freezeAndClone

    protected abstract E freezeAndClone(E value)

The implementing method must mark `value` as shared, and return a new object to use in its place. Hopefully, the majority of the work of the clone can be deferred by copy-on-write.

#### cloneFrozen

    protected abstract E cloneFrozen(E frozenValue)

Returns a clone of a frozen E.

#### clone

    public CopyOnWriteManager<E> clone()

Overrides:
  `clone` in class `Object`

#### read

    public E read()

Returns a reference to the tree structure suitable for a read operation. The returned structure may be mutated by operations that have the permission of this `CopyOnWriteManager`, but they will not observe changes managed by other instances.

#### beginMutation

    public Epoch.Ticket beginMutation()

Obtains permission to mutate the copy-on-write value held by this instance, perhaps blocking while a concurrent snapshot is being performed. `Epoch.Ticket.leave(int)` must be called exactly once on the object returned from this method, after the mutation has been completed. The change in size reflected by the mutation should be passed as the parameter to `leave`.

#### beginQuiescent

    public Epoch.Ticket beginQuiescent()

#### mutable

    public E mutable()

Returns a reference to the tree structure suitable for a mutating operation. This method may only be called under the protection of a ticket returned from `beginMutation()`.

#### frozen

    public E frozen()

Returns a reference to a snapshot of this instance's tree structure that may be read, but not written. This is accomplished by suspending mutation, replacing the mutable root of this manager with the result of `freezeAndClone(root, false)`, and then returning a reference to the old root. Successive calls to this method may return the same instance.

#### availableFrozen

    public E availableFrozen()

Returns a reference to a snapshot of this instance's tree structure, if one is available without requiring any additional copying, otherwise returns null. May be used in combination with `beginQuiescent()` to perform quiescent reads with minimal cost.

#### isEmpty

    public boolean isEmpty()

Returns true if the computed `size()` is zero.

#### size

    public int size()

Returns the sum of the `initialSize` parameter passed to the constructor, and the size deltas passed to `Epoch.Ticket.leave(int)` for all of the mutation tickets. The result returned is linearizable with mutations, which requires mutation to be quiesced. No tree freeze is required, however.

2017 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 2.1.0
Release Date | : July 20 2017