*
For information on
*
Functionally this interface defines some methods supporting garbage-free off-heap programming: * {@link #getUsing(Object, Object)}, {@link #acquireUsing(Object, Object)}. *
*
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. *
*
Note that {@code ChronicleMap} extends {@link Closeable}, don't forget to {@linkplain #close()
* close} map when it is no longer needed.
*
* @param
* If the value class allows reusing, consider {@link #getUsing(Object, Object)} method
* instead of this to reduce garbage creation. Read the section about usage
* patterns in the Chronicle Map 3 Tutorial for more.
*
* @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
* @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.
*
* If the specified key is present in the map, the value data is read to the provided {@code
* value} object via value reader's {@link SizedReader#read(net.openhft.chronicle.bytes.Bytes, long, Object)
* read(StreamingDataInput, size, value)} method. 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.
*
* 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.
*
* @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
* @see #get(Object)
* @see #acquireUsing(Object, Object)
* @see ChronicleMapBuilder#valueMarshallers(SizedReader, SizedWriter)
*/
V getUsing(K key, V usingValue);
/**
* Acquire a value for a key, creating if absent.
*
* If the specified key is absent in the map, {@linkplain
* ChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) default value provider} is
* called. Then this object is put to this map for the specified key.
*
* 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.
*
* In code, {@code acquireUsing} is specified as :
*
*
* Where {@code defaultValue(key)} returns {@link
* ChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) defaultValueProvider}.
*
* If the {@code ChronicleMap} is off-heap updatable, i. e. created via {@link
* ChronicleMapBuilder} builder (values are {@link Byteable}), there is one more option of what
* to do if the key is absent in the map. 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 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)
*/
V acquireUsing(@NotNull K key, V usingValue);
@NotNull
net.openhft.chronicle.core.io.Closeable acquireContext(@NotNull K key, @NotNull V usingValue);
/**
* Returns the result of application of the given function to the value to which the given key
* is mapped. If there is no mapping for the key, {@code null} is returned from {@code
* getMapped()} call without application of the given function. This method is primarily useful
* when accessing {@code ChronicleMap} implementation which delegates it's requests to some
* remote node (server) and pulls the result through serialization/deserialization path, and
* probably network. In this case, when you actually need only a part of the map value's state
* (e. g. a single field) it's cheaper to extract it on the server side and transmit lesser
* bytes.
*
* @param key the key whose associated value is to be queried
* @param function a function to transform the value to the actually needed result,
* which should be smaller than the map value
* @param
* see also {@see net.openhft.chronicle.map.ChronicleMap#remainingAutoResizes} as these operations are related.
*/
default short percentageFreeSpace() {
throw new UnsupportedOperationException("todo");
}
/**
* @return the number of times in the future the map can expand its capacity of each segment ( by expending its capacity we mean expending the maximum number of possible entries that
* can be stored into the map), the map will expand automatically. However, there is an upper limit to the number of times the map can expand.
* This limit is set via the {@code net.openhft.chronicle.map.ChronicleMapBuilder#maxBloatFactor} if the {@code remainingAutoResizes} drops to zero,
* then the map is no longer able to expand, if subsequently, the free space ( see {@link net.openhft.chronicle.map.ChronicleMap#percentageFreeSpace})
* in the map becomes low ( around 5% ), the map will not be able to take more entries and will fail with an {@code
* java.lang.IllegalStateException} for production systems it is recommended you periodically monitor the remainingAutoResizes and
* {@link net.openhft.chronicle.map.ChronicleMap#percentageFreeSpace}.
*/
default int remainingAutoResizes() {
throw new UnsupportedOperationException("todo");
}
}
{@code
* V acquireUsing(K key, V usingValue) {
* if (!containsKey(key))
* put(key, defaultValue(key));
* return getUsing(key, usingValue);
* }}
*