K
- the map key typeV
- the map value typepublic interface ChronicleMap<K,V> extends ConcurrentMap<K,V>, ChronicleHash
ConcurrentMap
interface, stores the data off-heap.
For information on
ChronicleMap
ChronicleMap
flavors and propertiesAbstractChronicleMapBuilder
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 | Method and Description |
---|---|
V |
acquireUsing(K key,
V usingValue)
Acquire a value for a key, creating if absent.
|
WriteContext<K,V> |
acquireUsingLocked(K key,
V usingValue) |
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. |
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. |
ReadContext<K,V> |
getUsingLocked(K key,
V usingValue)
The method is similar
getUsing(K key, V usingValue); but in addition read locks the map
segment to operations to be performed atomically. |
long |
longSize()
Returns the number of entries in this map.
|
putIfAbsent, remove, replace, replace
clear, containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, values
close, file
long longSize()
Map.size()
V get(Object key)
null
if this map contains no mapping
for the key.
If the value class allows reusing, particularly if it is a Byteable
subclass, consider
getUsing(Object, Object)
method instead of this to reduce garbage creation.
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 marshaller's read(Bytes, value)
or value
reader's 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 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.valueMarshaller(BytesMarshaller)
@NotNull ReadContext<K,V> getUsingLocked(@NotNull K key, @NotNull V usingValue)
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
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 readContext.value() uses the provided usingValue
object via value marshaller's read(Bytes,
value)
or value reader's 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 usingValue
object,
calling this method instead of get(Object)
could help to reduce garbage creation.
try (ReadContext>?, BondVOInterface< 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 ) } // the read lock is released here
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.The provided value
object is allowed to be null
, in this case
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if possibleget(Object)
,
getUsing(Object, Object)
,
ChronicleMapBuilder.valueMarshaller(BytesMarshaller)
V acquireUsing(@NotNull K key, V usingValue)
If the specified key if absent in the map, default value is taken or 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 either default value or defaultValueProvider.
If the ChronicleMap
is off-heap updatable, i. e. created via OffHeapUpdatableChronicleMapBuilder
builder (values are Byteable
), there is one more option of
what to do if the key is absent in the map, see 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.
key
- the key whose associated value is to be returnedusingValue
- the object to read value data in, if present. Can not be nullgetUsing(Object, Object)
@NotNull WriteContext<K,V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue)
Copyright © 2014. All rights reserved.