org.gridgain.grid.util.snaptree

Class CopyOnWriteManager<E>

java.lang.Object

org.gridgain.grid.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

Modifier and Type	Method and Description
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.