K
- the map key typeV
- the map value typepublic interface ChronicleMap<K,V> extends ConcurrentMap<K,V>, ChronicleHash<K,MapEntry<K,V>,MapSegmentContext<K,V,?>,ExternalMapQueryContext<K,V,?>>
ChronicleMap
provides concurrent access to a Chronicle Map key-value store from a
JVM process.
For information on
ChronicleMap
ChronicleMap
flavors and propertiesChronicleMapBuilder
documentation.
Functionally this interface defines some methods supporting garbage-free off-heap programming:
getUsing(Object, Object)
, acquireUsing(Object, Object)
.
Roughly speaking, ChronicleMap
compares keys and values by their binary serialized
form, that shouldn't necessary be the same equality relation as defined by built-in Object.equals(Object)
method, which is prescribed by general Map
contract.
Note that ChronicleMap
extends Closeable
, don't forget to close map when it is no longer needed.
Modifier and Type | Interface and Description |
---|---|
static class |
ChronicleMap.SegmentStats |
Modifier and Type | Method and Description |
---|---|
net.openhft.chronicle.core.io.Closeable |
acquireContext(K key,
V usingValue)
Acquires an update lock and a value for a key.
|
V |
acquireUsing(K key,
V usingValue)
Acquire a value for a key, creating if absent.
|
V |
get(Object key)
Returns the value to which the specified key is mapped, or
null if this map contains
no mapping for the key. |
void |
getAll(File toFile)
Exports all the entries to a
File storing them in JSON format, an attempt is
made where possible to use standard java serialisation and keep the data human readable, data
serialized using the custom serialises are converted to a binary format which is not human
readable but this is only done if the Keys or Values are not Serializable . |
<R> R |
getMapped(K key,
net.openhft.chronicle.core.util.SerializableFunction<? super V,R> function)
Returns the result of application of the given function to the value to which the given key
is mapped.
|
V |
getUsing(K key,
V usingValue)
Returns the value to which the specified key is mapped, read to the provided
value
object, if possible, or returns null , if this map contains no mapping for the key. |
default double |
maxBloatFactor()
The maximum number of times, the chronicle map is allowed to grow in size beyond
the configured number of entries.
|
static <K,V> ChronicleMapBuilder<K,V> |
of(Class<K> keyClass,
Class<V> valueClass)
Delegates to
ChronicleMapBuilder.of(Class, Class) for convenience. |
default short |
percentageFreeSpace()
WARNING: This is an expensive operation which can take milli-seconds.
|
void |
putAll(File fromFile)
Imports all the entries from a
File , the fromFile must be created
using or the same format as get(Object) , this method behaves
similar to Map.put(Object, Object) where existing
entries are overwritten. |
default int |
remainingAutoResizes() |
default ChronicleMap.SegmentStats[] |
segmentStats()
WARNING: This is a detailed however expensive operation which can take milliseconds
|
Class<V> |
valueClass() |
Type |
valueType() |
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll
clear, containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, values
close, file, forEachEntry, forEachEntryWhile, isOpen, keyClass, keyType, longSize, name, offHeapMemoryUsed, queryContext, queryContext, queryContext, segmentContext, segments, toIdentityString
isClosed
static <K,V> ChronicleMapBuilder<K,V> of(Class<K> keyClass, Class<V> valueClass)
ChronicleMapBuilder.of(Class, Class)
for convenience.K
- the key type of the Chronicle Map to createV
- the value type of the Chronicle Map to createkeyClass
- class of the key type of the Chronicle Map to createvalueClass
- class of the value type of the Chronicle Map to createChronicleMapBuilder
for the given key and value classesV get(Object key)
null
if this map contains
no mapping for the key.
If the value class allows reusing, consider 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.
get
in interface Map<K,V>
key
- the key whose associated value is to be returnednull
if no value is mappedgetUsing(Object, Object)
V getUsing(K key, V usingValue)
value
object, if possible, or returns 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 value
object via value reader's read(StreamingDataInput, size, value)
method. If the value deserializer is able to reuse the
given value
object, calling this method instead of get(Object)
could help to
reduce garbage creation.
The provided value
object is allowed to be null
, in this case map.getUsing(key, null)
call is semantically equivalent to simple map.get(key)
call.
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if possiblenull
if this map contains
no mapping for the keyget(Object)
,
acquireUsing(Object, Object)
,
ChronicleMapBuilder.valueMarshallers(SizedReader, SizedWriter)
V acquireUsing(@NotNull K key, V usingValue)
If the specified key is absent in the map, 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 getUsing(key, usingValue)
call,
passed the same key
and usingValue
as into this method call. This means, as
in getUsing(K, V)
, usingValue
could safely be null
, in this case a new
value instance is created to deserialize the data.
In code, acquireUsing
is specified as :
V acquireUsing(K key, V usingValue) {
if (!containsKey(key))
put(key, defaultValue(key));
return getUsing(key, usingValue);
}
Where defaultValue(key)
returns defaultValueProvider
.
If the ChronicleMap
is off-heap updatable, i. e. created via ChronicleMapBuilder
builder (values are 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.
Unless value type is a Byteable or a value-type (e.g. LongValue
),
it's strictly advised to set defaultValueProvider
explicitly. The value may be deserialized from a non-initialized memory region,
potentially causing marshalling errors.
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if present. Can be nullgetUsing(Object, Object)
@NotNull net.openhft.chronicle.core.io.Closeable acquireContext(@NotNull K key, @NotNull V usingValue)
Lock is released when returned Closeable
object is closed.
This method is effectively equivalent to acquireUsing(Object, Object)
except for the
update lock management policy: acquireUsing(Object, Object)
releases the lock right away.
If the specified key is absent in the map, default value provider is called. Then this object is put to this map for the specified key.
Unless value is a Byteable or a value-type (e.g. LongValue
),
it's strictly advised to set defaultValueProvider
explicitly. The value may be deserialized from a non-initialized memory region,
potentially causing marshalling errors.
Also, if value is not a Byteable or a value-type, changes on usingValue
are
not propagated to the map memory right away. Updated usingValue
is written to the map
when the control object is closed, before releasing the update lock.
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if present. Can be nullacquireUsing(Object, Object)
<R> R getMapped(K key, @NotNull net.openhft.chronicle.core.util.SerializableFunction<? super V,R> function)
null
is returned from getMapped()
call without application of the given function. This method is primarily useful
when accessing 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.R
- the result typekey
- the key whose associated value is to be queriedfunction
- a function to transform the value to the actually needed result,
which should be smaller than the map valuenull
if there
is no mapping for the keyvoid getAll(File toFile) throws IOException
File
storing them in JSON format, an attempt is
made where possible to use standard java serialisation and keep the data human readable, data
serialized using the custom serialises are converted to a binary format which is not human
readable but this is only done if the Keys or Values are not Serializable
.
This method can be used in conjunction with putAll(File)
and is
especially useful if you wish to import/export entries from one chronicle map into another.
This import and export of the entries can be performed even when the versions of ChronicleMap
differ. This method is not performant and as such we recommend it is not used in performance
sensitive code.toFile
- the file to store all the entries to, the entries will be stored in JSON
formatIOException
- its not possible store the data to toFile
putAll(File)
void putAll(File fromFile) throws IOException
File
, the fromFile
must be created
using or the same format as get(Object)
, this method behaves
similar to Map.put(Object, Object)
where existing
entries are overwritten. A write lock is only held while each individual entry is inserted
into the map, not over all the entries in the File
fromFile
- the file containing entries ( in JSON format ) which will be deserialized and
Map.put(Object, Object)
into the mapIOException
- its not possible read the fromFile
getAll(File)
Type valueType()
default short percentageFreeSpace()
net.openhft.chronicle.map.ChronicleMapBuilder#maxBloatFactor
. If the map
expands you will see an increase in the available free space. NOTE: It is not possible to expand the chronicle map manually.
as these operations are related.
default ChronicleMap.SegmentStats[] segmentStats()
default int remainingAutoResizes()
net.openhft.chronicle.map.ChronicleMapBuilder#maxBloatFactor
if the remainingAutoResizes
drops to zero,
then the map is no longer able to expand, if subsequently, the free space ( see percentageFreeSpace()
)
in the map becomes low ( around 5% ), the map will not be able to take more entries and will fail with an java.lang.IllegalStateException
for production systems it is recommended you periodically monitor the remainingAutoResizes and
percentageFreeSpace()
.default double maxBloatFactor()
The default maximum bloat factor factor is 1.0
- i. e. "no bloat is expected".
It is strongly advised not to configure maxBloatFactor
to more than 10.0
,
almost certainly, you either should configure ChronicleHash
es completely differently,
or this data store doesn't fit to your case.
Copyright © 2022. All rights reserved.