Alawn/Chronicle-Map
1
0
Fork 0
mirror of https://github.com/OpenHFT/Chronicle-Map.git synced 2021-09-13 01:26:12 +00:00
Code Releases Activity

HCOLL-155 improved documentation

Browse Source
This commit is contained in:
Rob Austin
2014-11-10 13:25:59 +00:00
parent b0dba6a779
commit 0edb2252fa
8 changed files with 71 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/main/java/net/openhft/chronicle/map/ChronicleMap.java
+54 -64
View File
@@ -32,19 +32,19 @@ import java.util.concurrent.ConcurrentMap;
/**
* Extension of {@link ConcurrentMap} interface, stores the data off-heap.
*
* <p>For information on <ul> <li>how to construct a {@code ChronicleMap}</li> <li>{@code
* ChronicleMap} flavors and properties</li> <li>available configurations</li> </ul> see {@link
* AbstractChronicleMapBuilder} documentation.
* <p>For information on <ul> <li>how to construct a {@code ChronicleMap}</li> <li>{@code ChronicleMap}
* flavors and properties</li> <li>available configurations</li> </ul> see {@link AbstractChronicleMapBuilder}
* documentation.
*
* <p>Functionally this interface defines some methods supporting garbage-free off-heap programming:
* {@link #getUsing(Object, Object)}, {@link #acquireUsing(Object, Object)}.
* <p>Functionally this interface defines some methods supporting garbage-free off-heap programming: {@link
* #getUsing(Object, Object)}, {@link #acquireUsing(Object, Object)}.
*
* <p>Roughly speaking, {@code ChronicleMap} compares keys and values by their binary serialized
* form, that shouldn't necessary be the same equality relation as defined by built-in {@link
* Object#equals(Object)} method, which is prescribed by general {@link Map} contract.
* <p>Roughly speaking, {@code ChronicleMap} compares keys and values by their binary serialized form, that
* shouldn't necessary be the same equality relation as defined by built-in {@link Object#equals(Object)}
* method, which is prescribed by general {@link Map} contract.
*
* <p>Note that {@code ChronicleMap} extends {@link Closeable}, don't forget to {@linkplain #close()
* close} map when it is no longer needed.
* <p>Note that {@code ChronicleMap} extends {@link Closeable}, don't forget to {@linkplain #close() close}
* map when it is no longer needed.
*
* @param <K> the map key type
* @param <V> the map value type
@@ -59,41 +59,38 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
long longSize();
/**
* Returns the value to which the specified key is mapped, or {@code null} if this map contains
* no mapping for the key.
* Returns the value to which the specified key is mapped, or {@code null} if this map contains no mapping
* for the key.
*
* <p>If the value class allows reusing, particularly if it is a {@link Byteable} subclass,
* consider {@link #getUsing(Object, Object)} method instead of this to reduce garbage
* creation.
* <p>If the value class allows reusing, particularly if it is a {@link Byteable} subclass, consider
* {@link #getUsing(Object, Object)} method instead of this to reduce garbage creation.
*
* @param key the key whose associated value is to be returned
* @return the value to which the specified key is mapped after this method call, or {@code
* null} if no value is mapped
* @return the value to which the specified key is mapped after this method call, or {@code null} if no
* value is mapped
* @see #getUsing(Object, Object)
*/
@Override
V get(Object key);
/**
* Returns the value to which the specified key is mapped, read to the provided {@code value}
* object, if possible, or returns {@code null}, if this map contains no mapping for the key.
* Returns the value to which the specified key is mapped, read to the provided {@code value} object, if
* possible, or returns {@code null}, if this map contains no mapping for the key.
*
* <p>If the specified key is present in the map, the value data is read to the provided {@code
* value} object via value marshaller's {@link BytesMarshaller#read(Bytes, Object) read(Bytes,
* value)} or value reader's {@link BytesReader#read(Bytes, long, Object) read(Bytes, size,
* value)} method, depending on what deserialization strategy is configured on the builder,
* using which this map was constructed. If the value deserializer is able to reuse the given
* {@code value} object, calling this method instead of {@link #get(Object)} could help to
* reduce garbage creation.
* <p>If the specified key is present in the map, the value data is read to the provided {@code value}
* object via value marshaller's {@link BytesMarshaller#read(Bytes, Object) read(Bytes, value)} or value
* reader's {@link BytesReader#read(Bytes, long, Object) read(Bytes, size, value)} method, depending on
* what deserialization strategy is configured on the builder, using which this map was constructed. If
* the value deserializer is able to reuse the given {@code value} object, calling this method instead of
* {@link #get(Object)} could help to reduce garbage creation.
*
* <p>The provided {@code value} object is allowed to be {@code null}, in this case {@code
* map.getUsing(key, null)} call is semantically equivalent to simple {@code map.get(key)}
* call.
* map.getUsing(key, null)} call is semantically equivalent to simple {@code map.get(key)} call.
*
* @param key the key whose associated value is to be returned
* @param usingValue the object to read value data in, if possible
* @return the value to which the specified key is mapped, or {@code null} if this map contains
* no mapping for the key
* @return the value to which the specified key is mapped, or {@code null} if this map contains no mapping
* for the key
* @see #get(Object)
* @see #acquireUsing(Object, Object)
* @see ChronicleMapBuilder#valueMarshaller(BytesMarshaller)
@@ -101,39 +98,36 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
V getUsing(K key, V usingValue);
/**
* The method is similar {@link V getUsing(K key, V usingValue);} but in addition read locks
* the map segment to operations to be performed atomically. ( see the example below )
* The method is similar {@link V getUsing(K key, V usingValue);} but in addition read locks the map
* segment to operations to be performed atomically. ( see the example below )
*
* Returns the ReadContext which holds a map segment lock and provides method to get the value
* ( to which the specified key is mapped) atomically ( see example below for an explanation ),
* read to the provided {@code value} object, if possible, or returns {@code null}, if this map
* contains no mapping for the key.
* Returns the ReadContext which holds a map segment lock and provides method to get the value ( to which
* the specified key is mapped) atomically ( see example below for an explanation ), read to the provided
* {@code value} object, if possible, or returns {@code null}, if this map contains no mapping for the
* key.
*
* <p>If the specified key is present in the map, the readContext.value() uses the
* provided {@code usingValue} object via value marshaller's {@link BytesMarshaller#read(Bytes,
* Object) read(Bytes, value)} or value reader's {@link BytesReader#read(Bytes, long, Object)
* read(Bytes, size, value)} method, depending on what deserialization strategy is configured on
* the builder, using which this map was constructed. If the value deserializer is able to reuse
* the given {@code usingValue} object, calling this method instead of {@link #get(Object)}
* could help to reduce garbage creation.
* <p>If the specified key is present in the map, the readContext.value() uses the provided {@code
* usingValue} object via value marshaller's {@link BytesMarshaller#read(Bytes, Object) read(Bytes,
* value)} or value reader's {@link BytesReader#read(Bytes, long, Object) read(Bytes, size, value)}
* method, depending on what deserialization strategy is configured on the builder, using which this map
* was constructed. If the value deserializer is able to reuse the given {@code usingValue} object,
* calling this method instead of {@link #get(Object)} could help to reduce garbage creation.
*
* <p> try (ReadContext&gt;?, BondVOInterface&lt; context = map.getUsingLocked(key,using)) {
* BondVOInterface bond = context.value().getValue();
*
* long issueDate = bond.getIssueDate(); String symbol = bond.getSymbol();
*
* // add your logic here ( the lock will ensure this bond can not be changed by another thread
* )
* // add your logic here ( the lock will ensure this bond can not be changed by another thread )
*
* } // the read lock is released here </p>
*
* To ensure that you can read the 'issueDate' and 'symbol' can be read atomically, these values
* must be read while the segment lock is in place.
* To ensure that you can read the 'issueDate' and 'symbol' can be read atomically, these values must be
* read while the segment lock is in place.
*
*
* <p>The provided {@code value} object is allowed to be {@code null}, in this case
*
* @param key the key whose associated value is to be returned
* @param usingValue the object to read value data in, if possible
* @return the read context containing the value to which the specified key is mapped
@@ -151,14 +145,13 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
*
* <p>If the specified key if absent in the map, {@linkplain AbstractChronicleMapBuilder#defaultValue(Object)
* default value} is taken or {@linkplain AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider)
* default value provider} is called. Then this object is put to this map for the specified
* key.
* default value provider} is called. Then this object is put to this map for the specified key.
*
* <p>Then, either if the key was initially absent in the map or already present, the value is
* deserialized just as during {@link #getUsing(Object, Object) getUsing(key, usingValue)} call,
* passed the same {@code key} and {@code usingValue} as into this method call. This means, as
* in {@link #getUsing}, {@code usingValue} could safely be {@code null}, in this case a new
* value instance is created to deserialize the data.
* deserialized just as during {@link #getUsing(Object, Object) getUsing(key, usingValue)} call, passed
* the same {@code key} and {@code usingValue} as into this method call. This means, as in {@link
* #getUsing}, {@code usingValue} could safely be {@code null}, in this case a new value instance is
* created to deserialize the data.
*
* <p>In code, {@code acquireUsing} is specified as <pre>{@code
* V acquireUsing(K key, V usingValue) {
@@ -167,27 +160,24 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
* return getUsing(key, usingValue);
* }}</pre> Where {@code defaultValue(key)} returns either {@linkplain
* AbstractChronicleMapBuilder#defaultValue(Object) default value} or {@link
* AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider)
* defaultValueProvider.}
* AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) defaultValueProvider.}
*
* <p>If the {@code ChronicleMap} is off-heap updatable, i. e. created via {@link
* OffHeapUpdatableChronicleMapBuilder} builder (values are {@link Byteable}), there is one more
* option of what to do if the key is absent in the map, see {@link
* OffHeapUpdatableChronicleMapBuilder#prepareValueBytesOnAcquire(PrepareValueBytes)}. By
* default, value bytes are just zeroed out, no default value, either provided for key or
* constant, is put for the absent key.
* OffHeapUpdatableChronicleMapBuilder} builder (values are {@link Byteable}), there is one more option of
* what to do if the key is absent in the map, see {@link OffHeapUpdatableChronicleMapBuilder#prepareValueBytesOnAcquire(PrepareValueBytes)}.
* By default, value bytes are just zeroed out, no default value, either provided for key or constant, is
* put for the absent key.
*
* @param key the key whose associated value is to be returned
* @param usingValue the object to read value data in, if possible
* @param usingValue the object to read value data in, if present. Can not be null
* @return value to which the given key is mapping after this call, either found or created
* @see #getUsing(Object, Object)
*/
public V acquireUsing(K key, V usingValue);
V acquireUsing(@NotNull K key, @NotNull V usingValue);
@NotNull
WriteContext<K, V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue);
}
src/main/java/net/openhft/chronicle/map/StatelessChronicleMap.java
+1 -1
View File
@@ -391,7 +391,7 @@ class StatelessChronicleMap<K, V> implements ChronicleMap<K, V>, Closeable {
}
public synchronized V acquireUsing(K key, V usingValue) {
public synchronized V acquireUsing(@NotNull K key, @NotNull V usingValue) {
throw new UnsupportedOperationException("acquireUsing() is not supported for stateless " +
"clients");
}
src/main/java/net/openhft/chronicle/map/VanillaChronicleMap.java
+1 -1
View File
@@ -390,7 +390,7 @@ class VanillaChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
@Override
public V acquireUsing(K key, V usingValue) {
public V acquireUsing(@NotNull K key, @NotNull V usingValue) {
try (WriteContext<K, V> kvContext = lookupUsing(key, usingValue, LockType.WRITE_LOCK)) {
src/main/java/net/openhft/chronicle/map/VanillaShortShortMultiMap.java
+2
View File
@@ -85,6 +85,8 @@ class VanillaShortShortMultiMap implements MultiMap {
* constructor as the second argument
*/
public static long sizeOfBitSetInBytes(long minCapacity) {
return VanillaIntIntMultiMap.sizeOfBitSetInBytes(minCapacity);
}
src/main/java/net/openhft/chronicle/map/WriteContext.java
-3
View File
@@ -22,9 +22,6 @@ package net.openhft.chronicle.map;
*/
public interface WriteContext<K, V> extends Context<K, V> {
void dontPutOnClose();
void removeEntry();
// todo I have no idea why we have this, as this will always be done on when calling close()
// void update();
}