HCOLL-318 added many documentation and examples; Empowerted ReplicableEntry interface, and changed Map/SetRemoteOperations contracts to allow implementing more agile reconciliation strategies

This commit is contained in:
leventov
2015-06-20 05:43:34 +03:00
parent 9746084998
commit 1d7f54635a
28 changed files with 4164 additions and 2862 deletions
@@ -19,17 +19,85 @@
package net.openhft.chronicle.map;
import net.openhft.chronicle.hash.Data;
import net.openhft.chronicle.map.replication.MapRemoteOperations;
import org.jetbrains.annotations.NotNull;
/**
* SPI interface for customizing "low-level" modification operations on {@link ChronicleMap}
* entries. All {@code ChronicleMap} modifications operate via and instance of this interface:
* entries. All {@code ChronicleMap} modifications operate via an instance of this interface:
* <ul>
* <li>Ordinary query operations: {@code map.put()}, {@code map.compute()}. In fact, the</li>
* <li>Ordinary query operations: {@code map.put()}, {@code map.compute()}, {@code map.remove()}
* </li>
* <li>Operations with entry during iterations on the map, or the key/value/entry views,
* like {@code iterator.remove()}.</li>
* <li>Remote map operation calls and Replicated {@code ChronicleMap} reconciliation operations:
* see {@link MapRemoteOperations}.</li>
* </ul>
*
* <p>By default {@link #remove}, {@link #insert} and {@link #replaceValue} return {@code null},
* but subclasses could return something more sensible, to be used in higher-level SPI interfaces,
* namely {@link MapMethods} and {@link MapRemoteOperations}. For example, in bidirectional map
* implementation (i. e. a map that preserves the uniqueness of its values as well as that of
* its keys), that includes two {@code ChronicleMaps}, the {@code MapEntryOperations}' methods return
* type could be used to indicate if we were successful to lock both maps before performing
* the update: <pre>{@code
* enum DualLockSuccess {SUCCESS, FAIL}
*
* class BiMapEntryOperations<K, V> implements MapEntryOperations<K, V, DualLockSuccess> {
* ChronicleMap<V, K> reverse;
*
* public void setReverse(ChronicleMap<V, K> reverse) {
* this.reverse = reverse;
* }
*
* @Override
* public DualLockSuccess remove(@NotNull MapEntry<K, V> entry) {
* try (ExternalMapQueryContext<V, K, ?> rq = reverse.queryContext(entry.value())) {
* if (!rq.updateLock().tryLock()) {
* if (entry.context() instanceof MapQueryContext)
* return FAIL;
* throw new IllegalStateException("Concurrent modifications to reverse map " +
* "during remove during iteration");
* }
* MapEntry<V, K> reverseEntry = rq.entry();
* if (reverseEntry != null) {
* entry.doRemove();
* reverseEntry.doRemove();
* return SUCCESS;
* } else {
* throw new IllegalStateException(entry.key() + " maps to " + entry.value() +
* ", but in the reverse map this value is absent");
* }
* }
* }
*
* // ... other methods
* }
*
* class BiMapMethods<K, V> implements MapMethods<K, V, DualLockSuccess> {
* @Override
* public void remove(MapQueryContext<K, V, DualLockSuccess> q, ReturnValue<V> returnValue) {
* while (true) {
* q.updateLock().lock();
* try {
* MapEntry<K, V> entry = q.entry();
* if (entry != null) {
* returnValue.returnValue(entry.value());
* if (q.remove(entry) == SUCCESS)
* return;
* }
* } finally {
* q.readLock().unlock();
* }
* }
* }
*
* // ... other methods
* }}</pre>
*
* @param <K> the map key type
* @param <V> the map value type
* @param <R> methods return type, used for communication between lower- and higher-level SPI
* @see ChronicleMapBuilder#entryOperations(MapEntryOperations)
*/
public interface MapEntryOperations<K, V, R> {
@@ -43,6 +111,7 @@ public interface MapEntryOperations<K, V, R> {
* @param entry the entry to remove
* @throws IllegalStateException if some locking/state conditions required to perform remove
* operation are not met
* @throws RuntimeException if removal was unconditionally unsuccessful due to any reason
*/
default R remove(@NotNull MapEntry<K, V> entry) {
entry.doRemove();
@@ -52,9 +121,14 @@ public interface MapEntryOperations<K, V, R> {
/**
* Replaces the given entry's value with the new one.
*
* @implNote default implementation calls {@link MapEntry#doReplaceValue(Data)
* entry.doReplaceValue(newValue)} and returns {@code null}.
*
* @param entry the entry to replace the value in
* @throws IllegalStateException if some locking/state conditions required to perform replace
* operation are not met
* @throws RuntimeException if value replacement was unconditionally unsuccessful due
* to any reason
*/
default R replaceValue(@NotNull MapEntry<K, V> entry, Data<V, ?> newValue) {
entry.doReplaceValue(newValue);
@@ -64,11 +138,13 @@ public interface MapEntryOperations<K, V, R> {
/**
* Inserts the new entry into the map, of {@link MapAbsentEntry#absentKey() the key} from
* the given insertion context (<code>absentEntry</code>) and the given {@code value}.
* Returns {@code true} if the insertion was successful, {@code false} if it was discarded
* for any reason.
*
* @implNote default implementation calls {@link MapAbsentEntry#doInsert(Data)
* absentEntry.doInsert(value)} and returns {@code null}.
*
* @throws IllegalStateException if some locking/state conditions required to perform insertion
* operation are not met
* @throws RuntimeException if insertion was unconditionally unsuccessful due to any reason
*/
default R insert(@NotNull MapAbsentEntry<K, V> absentEntry, Data<V, ?> value) {
absentEntry.doInsert(value);