K - key type of the maps, produced by this builderV - value type of the maps, produced by this builderpublic final class ChronicleMapBuilder<K,V> extends Object implements ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
ChronicleMapBuilder manages ChronicleMap configurations; could be used as a
classic builder and/or factory. This means that in addition to the standard builder usage
pattern:
ChronicleMap<Key, Value> map = ChronicleMapOnHeapUpdatableBuilder
.of(Key.class, Value.class)
// ... other configurations
.create();
ChronicleMapBuilder<Key, Value> builder = ChronicleMapBuilder
.of(Key.class, Value.class)
.entries(..)
// ... other configurations
<p>
ChronicleMap<Key, Value> map1 = builder.create();
ChronicleMap<Key, Value> map2 = builder.create();ChronicleMap instances don't depend on the builder.
ChronicleMapBuilder is mutable, see a note in ChronicleHashBuilder interface
documentation.
Later in this documentation, "ChronicleMap" means "ChronicleMaps, created by ChronicleMapBuilder", unless specified different, because theoretically someone might provide
ChronicleMap implementations with completely different properties.
In addition to the key and value types, you must configure number of entries you are going to insert into the created map at most. See entries(long) method documentation for more information on this.
If you key or value type is not constantly sized and known to ChronicleHashBuilder, i.
e. it is not a boxed primitive, value interface,
or Byteable, you must provide the ChronicleHashBuilder with some
information about you keys or values: if they are constantly-sized, call constantKeySizeBySample(Object), otherwise averageKey(Object) or averageKeySize(double) method, and accordingly for values.
There are some JVM-level configurations, which are not stored in the ChronicleMap's persistence
file (or the other way to say this: they are not parts of the Chronicle Map data store
specification) and have to be configured explicitly for each created on-heap ChronicleMap instance, even if it is a view of an existing Chronicle Map data store. On the
other hand, JVM-level configurations could be different for different views of the same Chronicle
Map data store. The list of JVM-level configurations:
ChronicleHashBuilder,
ChronicleMap,
ChronicleSetBuilder| Modifier and Type | Method and Description |
|---|---|
ChronicleMapBuilder<K,V> |
actualChunkSize(int actualChunkSize)
Configures the size in bytes of allocation unit of hash container instances, created by this
builder.
|
ChronicleMapBuilder<K,V> |
actualChunksPerSegmentTier(long actualChunksPerSegmentTier)
Configures the actual number of chunks, that will be reserved for any single segment tier of
the hash containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
actualSegments(int actualSegments)
Configures the actual number of segments in the hash containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
aligned64BitMemoryOperationsAtomic(boolean aligned64BitMemoryOperationsAtomic)
Specifies whether on the current combination of platform, OS and Jvm aligned 8-byte reads
and writes are atomic or not.
|
ChronicleMapBuilder<K,V> |
allowSegmentTiering(boolean allowSegmentTiering)
In addition to
maxBloatFactor(1.0), that does not
guarantee that segments won't tier (due to bad hash distribution or natural variance),
configuring allowSegmentTiering(false) makes Chronicle Hashes, created by this
builder, to throw IllegalStateException immediately when some segment overflows. |
ChronicleMapBuilder<K,V> |
averageKey(K averageKey)
Configures the average number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder, by serializing the given
averageKey using
the configured keys marshallers. |
ChronicleMapBuilder<K,V> |
averageKeySize(double averageKeySize)
Configures the average number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
averageValue(V averageValue)
Configures the average number of bytes, taken by serialized form of values, put into maps,
created by this builder, by serializing the given
averageValue using the configured
value marshallers. |
ChronicleMapBuilder<K,V> |
averageValueSize(double averageValueSize)
Configures the average number of bytes, taken by serialized form of values, put into maps,
created by this builder.
|
ChronicleMapBuilder<K,V> |
checksumEntries(boolean checksumEntries)
Configures whether hash containers, created by this builder, should compute and store entry
checksums.
|
ChronicleMapBuilder<K,V> |
clone()
Clones this builder.
|
ChronicleMapBuilder<K,V> |
constantKeySizeBySample(K sampleKey)
Configures the constant number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder.
|
boolean |
constantlySizedKeys() |
boolean |
constantlySizedValues() |
ChronicleMapBuilder<K,V> |
constantValueSizeBySample(V sampleValue)
Configures the constant number of bytes, taken by serialized form of values, put into maps,
created by this builder.
|
ChronicleMap<K,V> |
create()
Creates a new hash container from this builder, storing it's data in off-heap memory, not
mapped to any file.
|
ChronicleMap<K,V> |
createOrRecoverPersistedTo(File file)
Recovers and opens the hash container, persisted to the specified file, or creates a new one
from this builder, if the file doesn't exist yet, and maps its off-heap memory to the file.
|
ChronicleMap<K,V> |
createOrRecoverPersistedTo(File file,
boolean sameLibraryVersion)
Recovers and opens the hash container, persisted to the specified file, or creates a new one
from this builder, if the file doesn't exist yet, and maps its off-heap memory to the file.
|
ChronicleMap<K,V> |
createOrRecoverPersistedTo(File file,
boolean sameLibraryVersion,
ChronicleHashCorruption.Listener corruptionListener)
Recovers and opens the hash container, persisted to the specified file, or creates a new one
from this builder, if the file doesn't exist yet, and maps its off-heap memory to the file.
|
ChronicleMap<K,V> |
createPersistedTo(File file)
Opens a hash container residing the specified file, or creates a new one from this builder,
if the file doesn't yet exist and maps its off-heap memory to the file.
|
ChronicleMapBuilder<K,V> |
defaultValueProvider(DefaultValueProvider<K,V> defaultValueProvider)
Specifies the function to obtain a value for the key during
acquireUsing() calls, if the key is absent in the map, created by this builder. |
ChronicleMapBuilder<K,V> |
entries(long entries)
Configures the target number of entries, that is going be inserted into the hash containers,
created by this builder.
|
ChronicleMapBuilder<K,V> |
entriesPerSegment(long entriesPerSegment)
Configures the actual maximum number entries, that could be inserted into any single segment
of the hash containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
entryAndValueOffsetAlignment(int alignment)
Configures alignment of address in memory of entries and independently of address in memory
of values within entries ((i.
|
ChronicleMapBuilder<K,V> |
entryOperations(MapEntryOperations<K,V,?> entryOperations)
Inject your SPI code around basic
ChronicleMap's operations with entries:
removing entries, replacing entries' value and inserting new entries. |
boolean |
equals(Object o) |
int |
hashCode() |
<M extends BytesReader<K> & BytesWriter<? super K>> |
keyMarshaller(M marshaller)
Shortcut for
keyMarshallers(marshaller, marshaller). |
<M extends SizedReader<K> & SizedWriter<? super K>> |
keyMarshaller(M sizedMarshaller)
Shortcut for
keyMarshallers(sizedMarshaller, sizedMarshaller). |
ChronicleMapBuilder<K,V> |
keyMarshallers(BytesReader<K> keyReader,
BytesWriter<? super K> keyWriter)
Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in
hash containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
keyMarshallers(SizedReader<K> keyReader,
SizedWriter<? super K> keyWriter)
Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in
hash containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
keyReaderAndDataAccess(SizedReader<K> keyReader,
DataAccess<K> keyDataAccess)
Configures the
DataAccess and SizedReader used to serialize and deserialize
keys to and from off-heap memory in hash containers, created by this builder. |
ChronicleMapBuilder<K,V> |
keySizeMarshaller(SizeMarshaller keySizeMarshaller)
Configures the marshaller used to serialize actual key sizes to off-heap memory in hash
containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
mapMethods(MapMethods<K,V,?> mapMethods)
Inject your SPI around logic of all
ChronicleMap's operations with individual keys:
from Map.containsKey(java.lang.Object) to ChronicleMap.acquireUsing(K, V) and
ConcurrentMap.merge(K, V, java.util.function.BiFunction<? super V, ? super V, ? extends V>). |
double |
maxBloatFactor() |
ChronicleMapBuilder<K,V> |
maxBloatFactor(double maxBloatFactor)
Configures the maximum number of times, the hash containers, created by this builder,
are allowed to grow in size beyond the configured target number
of entries.
|
ChronicleMapBuilder<K,V> |
maxChunksPerEntry(int maxChunksPerEntry)
Configures how many chunks a single entry, inserted into
ChronicleHashes, created
by this builder, could take. |
ChronicleMapBuilder<K,V> |
minSegments(int minSegments)
Set minimum number of segments in hash containers, constructed by this builder.
|
ChronicleMapBuilder<K,V> |
name(String name)
Specify the name which will be given to a ChronicleHash, created by this builder.
|
ChronicleMapBuilder<K,V> |
nonTieredSegmentsPercentile(double nonTieredSegmentsPercentile)
Configures probabilistic fraction of segments, which shouldn't become tiered, if Chronicle
Hash size is
ChronicleHashBuilder.entries(long), assuming hash code distribution of the keys, inserted
into configured Chronicle Hash, is good. |
static <K,V> ChronicleMapBuilder<K,V> |
of(Class<K> keyClass,
Class<V> valueClass)
Returns a new
ChronicleMapBuilder instance which is able to create maps with the specified key and value classes. |
Object |
privateAPI()
Deprecated.
don't use private API in the client code
|
ChronicleMapBuilder<K,V> |
putReturnsNull(boolean putReturnsNull)
Configures if the maps created by this
ChronicleMapBuilder should return null
instead of previous mapped values on ChornicleMap.put(key, value) calls. |
ChronicleMap<K,V> |
recoverPersistedTo(File file,
boolean sameBuilderConfigAndLibraryVersion)
Recovers and opens the hash container, persisted to the specified file.
|
ChronicleMap<K,V> |
recoverPersistedTo(File file,
boolean sameBuilderConfigAndLibraryVersion,
ChronicleHashCorruption.Listener corruptionListener)
Recovers and opens the hash container, persisted to the specified file.
|
ChronicleMapBuilder<K,V> |
removeReturnsNull(boolean removeReturnsNull)
Configures if the maps created by this
ChronicleMapBuilder should return null
instead of the last mapped value on ChronicleMap.remove(key) calls. |
ChronicleMapBuilder<K,V> |
replicatedMapClassName(String replicatedMapClassName) |
ChronicleMapBuilder<K,V> |
replication(byte identifier) |
ChronicleMapBuilder<K,V> |
setPreShutdownAction(Runnable preShutdownAction)
A
ChronicleHash created using this builder is closed using a JVM shutdown hook. |
static <K,V> ChronicleMapBuilder<K,V> |
simpleMapOf(Class<K> keyClass,
Class<V> valueClass)
Returns a new
ChronicleMapBuilder instance which is able to create maps with the specified key and value classes. |
ChronicleMapBuilder<K,V> |
skipCloseOnExitHook(boolean skipCloseOnExitHook)
Skips the default automatic close configuration on the
ChronicleHash created by
this builder. |
String |
toString() |
void |
validateAlignment(int ifSet,
int actualChunkSize,
int alignment) |
<M extends BytesReader<V> & BytesWriter<? super V>> |
valueMarshaller(M marshaller)
Shortcut for
valueMarshallers(marshaller, marshaller). |
<M extends SizedReader<V> & SizedWriter<? super V>> |
valueMarshaller(M sizedMarshaller)
Shortcut for
valueMarshallers(sizedMarshaller, sizedMarshaller). |
ChronicleMapBuilder<K,V> |
valueMarshallers(BytesReader<V> valueReader,
BytesWriter<? super V> valueWriter)
Configures the marshallers, used to serialize/deserialize values to/from off-heap memory in
maps, created by this builder.
|
ChronicleMapBuilder<K,V> |
valueMarshallers(SizedReader<V> valueReader,
SizedWriter<? super V> valueWriter)
Configures the marshallers, used to serialize/deserialize values to/from off-heap memory in
maps, created by this builder.
|
ChronicleMapBuilder<K,V> |
valueReaderAndDataAccess(SizedReader<V> valueReader,
DataAccess<V> valueDataAccess)
Configures the
DataAccess and SizedReader used to serialize and deserialize
values to and from off-heap memory in maps, created by this builder. |
ChronicleMapBuilder<K,V> |
valueSizeMarshaller(SizeMarshaller valueSizeMarshaller)
Configures the marshaller used to serialize actual value sizes to off-heap memory in maps,
created by this builder.
|
public static <K,V> ChronicleMapBuilder<K,V> of(@NotNull Class<K> keyClass, @NotNull Class<V> valueClass)
ChronicleMapBuilder instance which is able to create maps with the specified key and value classes.K - key type of the maps, created by the returned builderV - value type of the maps, created by the returned builderkeyClass - class object used to infer key type and discover it's properties via
reflectionvalueClass - class object used to infer value type and discover it's properties via
reflectionpublic static <K,V> ChronicleMapBuilder<K,V> simpleMapOf(@NotNull Class<K> keyClass, @NotNull Class<V> valueClass)
ChronicleMapBuilder instance which is able to create maps with the specified key and value classes. It makes some assumptions about the size of entries
and the marshallers usedK - key type of the maps, created by the returned builderV - value type of the maps, created by the returned builderkeyClass - class object used to infer key type and discover it's properties via
reflectionvalueClass - class object used to infer value type and discover it's properties via
reflectionpublic ChronicleMapBuilder<K,V> clone()
ChronicleHashBuilderChronicleHashBuilders are mutable and changed on each configuration method call. Original
and cloned builders are independent.clone in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>clone in class Object@Deprecated public Object privateAPI()
privateAPI in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>public ChronicleMapBuilder<K,V> name(String name)
ChronicleHash, because this
name is used when logging errors and warnings inside Chronicle Map library itself, so having
the concrete ChronicleHash name in logs may help to debug.
name() is a JVM-level configuration, it is not stored in the persistence file (or
the other way to say this: they are not parts of the Chronicle Map data store
specification) and have to be configured explicitly for each created on-heap ChronicleHash instance, even if it is a view of an existing Chronicle Map data store. On the
other hand, name() could be different for different views of the same Chronicle
Map data store.
Read more about JVM-level configurations.
name in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>name - the name for a ChronicleHash, created by this builderChronicleHash.name()public ChronicleMapBuilder<K,V> averageKeySize(double averageKeySize)
ChronicleHashBuilder.averageKey(Object) might
be easier to use and more reliable. If key size is always the same, call ChronicleHashBuilder.constantKeySizeBySample(Object) method instead of this one.
ChronicleHashBuilder implementation heuristically chooses
the actual chunk size based on this configuration, that,
however, might result to quite high internal fragmentation, i. e. losses because only
integral number of chunks could be allocated for the entry. If you want to avoid this, you
should manually configure the actual chunk size in addition to this average key size
configuration, which is anyway needed.
If key is a boxed primitive type, a value interface or Byteable subclass, i. e. if
key size is known statically, it is automatically accounted and shouldn't be specified by
user.
Calling this method clears any previous ChronicleHashBuilder.constantKeySizeBySample(Object) and
ChronicleHashBuilder.averageKey(Object) configurations.
Example: if keys in your map(s) are English words in String form, average English
word length is 5.1, configure average key size of 6:
ChronicleMap<String, LongValue> wordFrequencies = ChronicleMapBuilder
.of(String.class, LongValue.class)
.entries(50000)
.averageKeySize(6)
.create();String
encoding is UTF-8 in ChronicleMap.)averageKeySize in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>averageKeySize - the average size of the keyIllegalStateException - if key size is known statically and shouldn't be configured
by userIllegalArgumentException - if the given keySize is non-positiveaverageKey(Object),
constantKeySizeBySample(Object),
averageValueSize(double),
actualChunkSize(int)public ChronicleMapBuilder<K,V> averageKey(K averageKey)
averageKey using
the configured keys marshallers.
In some cases, ChronicleHashBuilder.averageKeySize(double) might be easier to use, than constructing the
"average key". If key size is always the same, call ChronicleHashBuilder.constantKeySizeBySample(
Object) method instead of this one.
ChronicleHashBuilder implementation heuristically chooses
the actual chunk size based on this configuration, that,
however, might result to quite high internal fragmentation, i. e. losses because only
integral number of chunks could be allocated for the entry. If you want to avoid this, you
should manually configure the actual chunk size in addition to this average key size
configuration, which is anyway needed.
If key is a boxed primitive type or Byteable subclass, i. e. if key size is known
statically, it is automatically accounted and shouldn't be specified by user.
Calling this method clears any previous ChronicleHashBuilder.constantKeySizeBySample(Object) and
ChronicleHashBuilder.averageKeySize(double) configurations.
averageKey in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>averageKey - the average (by footprint in serialized form) key, is going to be put
into the hash containers, created by this builderNullPointerException - if the given averageKey is nullaverageKeySize(double),
constantKeySizeBySample(Object),
averageValue(Object),
actualChunkSize(int)public ChronicleMapBuilder<K,V> constantKeySizeBySample(K sampleKey)
sampleKey, all
keys should take the same number of bytes in serialized form, as this sample object.
If keys are of boxed primitive type or Byteable subclass, i. e. if key size is
known statically, it is automatically accounted and this method shouldn't be called.
If key size varies, method ChronicleHashBuilder.averageKeySize(double) should be called instead of
this one.
Calling this method clears any previous ChronicleHashBuilder.averageKey(Object) and
ChronicleHashBuilder.averageKeySize(double) configurations.
For example, if your keys are Git commit hashes:
Map<byte[], String> gitCommitMessagesByHash =
ChronicleMapBuilder.of(byte[].class, String.class)
.constantKeySizeBySample(new byte[20])
.create();constantKeySizeBySample in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>sampleKey - the sample keyaverageKeySize(double),
averageKey(Object),
constantValueSizeBySample(Object)public ChronicleMapBuilder<K,V> averageValueSize(double averageValueSize)
averageValue(Object) might be easier
to use and more reliable. If value size is always the same, call constantValueSizeBySample(Object) method instead of this one.
ChronicleHashBuilder implementation heuristically chooses the actual chunk size based on this configuration and the key size,
that, however, might result to quite high internal fragmentation, i. e. losses because only
integral number of chunks could be allocated for the entry. If you want to avoid this, you
should manually configure the actual chunk size in addition to this average value size
configuration, which is anyway needed.
If values are of boxed primitive type or Byteable subclass, i. e. if value size is
known statically, it is automatically accounted and shouldn't be specified by user.
Calling this method clears any previous constantValueSizeBySample(Object) and
averageValue(Object) configurations.
averageValueSize - number of bytes, taken by serialized form of valuesIllegalStateException - if value size is known statically and shouldn't be
configured by userIllegalArgumentException - if the given averageValueSize is non-positiveaverageValue(Object),
constantValueSizeBySample(Object),
averageKeySize(double),
actualChunkSize(int)public ChronicleMapBuilder<K,V> averageValue(V averageValue)
averageValue using the configured
value marshallers. In some cases, averageValueSize(double) might be easier to use, than constructing the "average value".
If value size is always the same, call constantValueSizeBySample(Object) method
instead of this one.
ChronicleHashBuilder implementation heuristically chooses the actual chunk size based on this configuration and the key size,
that, however, might result to quite high internal fragmentation, i. e. losses because only
integral number of chunks could be allocated for the entry. If you want to avoid this, you
should manually configure the actual chunk size in addition to this average value size
configuration, which is anyway needed.
If values are of boxed primitive type or Byteable subclass, i. e. if value size is
known statically, it is automatically accounted and shouldn't be specified by user.
Calling this method clears any previous constantValueSizeBySample(Object)
and averageValueSize(double) configurations.
averageValue - the average (by footprint in serialized form) value, is going to be put
into the maps, created by this builderNullPointerException - if the given averageValue is nullaverageValueSize(double),
constantValueSizeBySample(Object),
averageKey(Object),
actualChunkSize(int)public ChronicleMapBuilder<K,V> constantValueSizeBySample(V sampleValue)
sampleValue, all values should
take the same number of bytes in serialized form, as this sample object.
If values are of boxed primitive type or Byteable subclass, i. e. if value size is
known statically, it is automatically accounted and this method shouldn't be called.
If value size varies, method averageValue(Object) or averageValueSize(double) should be called instead of this one.
Calling this method clears any previous averageValue(Object) and
averageValueSize(double) configurations.
sampleValue - the sample valueaverageValueSize(double),
averageValue(Object),
constantKeySizeBySample(Object)public ChronicleMapBuilder<K,V> actualChunkSize(int actualChunkSize)
ChronicleMap and ChronicleSet store their data off-heap, so it is required
to serialize key (and values, in ChronicleMap case) (unless they are direct Byteable instances). Serialized key bytes (+ serialized value bytes, in ChronicleMap
case) + some metadata bytes comprise "entry space", which ChronicleMap or ChronicleSet should allocate. So chunk size is the minimum allocation portion in the
hash containers, created by this builder. E. g. if chunk size is 100, the created container
could only allocate 100, 200, 300... bytes for an entry. If say 150 bytes of entry space are
required by the entry, 200 bytes will be allocated, 150 used and 50 wasted. This is called
internal fragmentation.
To minimize memory overuse and improve speed, you should pay decent attention to this configuration. Alternatively, you can just trust the heuristics and doesn't configure the chunk size.
Specify chunk size so that most entries would take from 5 to several dozens of chunks. However, remember that operations with entries that span several chunks are a bit slower, than with entries which take a single chunk. Particularly avoid entries to take more than 64 chunks.
Example: if values in your ChronicleMap are adjacency lists of some social graph,
where nodes are represented as long ids, and adjacency lists are serialized in
efficient manner, for example as long[] arrays. Typical number of connections is
100-300, maximum is 3000. In this case chunk size of
30 * (8 bytes for each id) = 240 bytes would be a good choice:
Map<Long, long[]> socialGraph = ChronicleMapBuilder
.of(Long.class, long[].class)
.entries(1_000_000_000L)
.averageValueSize(150 * 8) // 150 is average adjacency list size
.actualChunkSize(30 * 8) // average 5-6 chunks per entry
.create();
This is a low-level configuration. The configured number of bytes is used as-is, without anything like round-up to the multiple of 8 or 16, or any other adjustment.
actualChunkSize in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>actualChunkSize - the "chunk size" in bytesIllegalStateException - is sizes of both keys and values of maps created by this
builder are constant, hence chunk size shouldn't be configured by userentryAndValueOffsetAlignment(int),
entries(long),
maxChunksPerEntry(int)public boolean constantlySizedKeys()
public ChronicleMapBuilder<K,V> maxChunksPerEntry(int maxChunksPerEntry)
ChronicleHashBuilderChronicleHashes, created
by this builder, could take. If you try to insert larger entry, IllegalStateException
is fired. This is useful as self-check, that you configured chunk size right and you
keys (and values, in ChronicleMap case) take expected number of bytes. For example,
if ChronicleHashBuilder.constantKeySizeBySample(Object) is configured or key size is statically known
to be constant (boxed primitives, data value generated implementations, Byteables,
etc.), and the same for value objects in ChronicleMap case, max chunks per entry
is configured to 1, to ensure keys and values are actually constantly-sized.maxChunksPerEntry in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>maxChunksPerEntry - how many chunks a single entry could span at mostChronicleHashBuilder.actualChunkSize(int)public boolean constantlySizedValues()
public ChronicleMapBuilder<K,V> entryAndValueOffsetAlignment(int alignment)
Useful when values of the map are updated intensively, particularly fields with volatile access, because it doesn't work well if the value crosses cache lines. Also, on some (nowadays rare) architectures any misaligned memory access is more expensive than aligned.
If values couldn't reference off-heap memory (i. e. it is not Byteable or a value
interface), alignment configuration makes no sense.
Default is ValueModel.recommendedOffsetAlignment() if the value type is a value
interface, otherwise 1 (that is effectively no alignment) or chosen heuristically (configure
explicitly for being sure and to compare performance in your case).
alignment - the new alignment of the maps constructed by this builderIllegalStateException - if values of maps, created by this builder, couldn't reference
off-heap memorypublic void validateAlignment(int ifSet,
int actualChunkSize,
int alignment)
public ChronicleMapBuilder<K,V> entries(long entries)
ChronicleHashBuilderChronicleHashBuilder.maxBloatFactor(double) is configured to 1.0
(and this is by default), this number of entries is also the maximum. If you try to insert
more entries, than the configured maxBloatFactor, multiplied by the given number of
entries, IllegalStateException might be thrown.
This configuration should represent the expected maximum number of entries in a stable
state, maxBloatFactor - the maximum bloat up coefficient,
during exceptional bursts.
To be more precise - try to configure the entries so, that the created hash
container is going to serve about 99% requests being less or equal than this number
of entries in size.
You shouldn't put additional margin over the actual target number of entries.
This bad practice was popularized by HashMap.HashMap(int) and HashSet.HashSet(int) constructors, which accept capacity, that should be multiplied
by load factor to obtain the actual maximum expected number of entries.
ChronicleMap and ChronicleSet don't have a notion of load factor.
The default target number of entries is 2^20 (~ 1 million).
entries in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>entries - the target size of the maps or sets, created by this builderChronicleHashBuilder.maxBloatFactor(double)public ChronicleMapBuilder<K,V> entriesPerSegment(long entriesPerSegment)
ChronicleHashBuilderChronicleHashBuilder.entries(long) configuration.
This is a low-level configuration.
entriesPerSegment in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>entriesPerSegment - the actual maximum number entries per segment in the
hash containers, created by this builderChronicleHashBuilder.entries(long),
ChronicleHashBuilder.actualSegments(int)public ChronicleMapBuilder<K,V> actualChunksPerSegmentTier(long actualChunksPerSegmentTier)
ChronicleHashBuilderChronicleHashBuilder.entriesPerSegment(long). Makes sense only if ChronicleHashBuilder.actualChunkSize(int),
ChronicleHashBuilder.actualSegments(int) and ChronicleHashBuilder.entriesPerSegment(long) are also configured
manually.actualChunksPerSegmentTier in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>actualChunksPerSegmentTier - the actual number of chunks, reserved per segment tier in
the hash containers, created by this builderpublic ChronicleMapBuilder<K,V> minSegments(int minSegments)
ChronicleHashBuilderConcurrentHashMap.minSegments in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>minSegments - the minimum number of segments in containers, constructed by this builderpublic ChronicleMapBuilder<K,V> actualSegments(int actualSegments)
ChronicleHashBuilderChronicleHashBuilder.entries(long) call.
This is a low-level configuration. The configured number is used as-is, without anything like round-up to the closest power of 2.
actualSegments in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>actualSegments - the actual number of segments in hash containers, created by
this builderChronicleHashBuilder.minSegments(int),
ChronicleHashBuilder.entriesPerSegment(long)public ChronicleMapBuilder<K,V> putReturnsNull(boolean putReturnsNull)
ChronicleMapBuilder should return null
instead of previous mapped values on ChornicleMap.put(key, value) calls.
Map.put() returns the previous value, functionality
which is rarely used but fairly cheap for simple in-process, on-heap implementations like
HashMap. But an off-heap collection has to create a new object and deserialize
the data from off-heap memory. A collection hiding remote queries over the network should
send the value back in addition to that. It's expensive for something you probably don't use.
This is a JVM-level configuration.
By default, ChronicleMap conforms the general Map contract and returns the
previous mapped value on put() calls.
putReturnsNull - true if you want ChronicleMap.put() to not return the value that was replaced but
instead return nullremoveReturnsNull(boolean)public ChronicleMapBuilder<K,V> removeReturnsNull(boolean removeReturnsNull)
ChronicleMapBuilder should return null
instead of the last mapped value on ChronicleMap.remove(key) calls.
Map.remove() returns the previous value, functionality which is
rarely used but fairly cheap for simple in-process, on-heap implementations like HashMap. But an off-heap collection has to create a new object and deserialize the data
from off-heap memory. A collection hiding remote queries over the network should send
the value back in addition to that. It's expensive for something you probably don't use.
This is a JVM-level configuration.
By default, ChronicleMap conforms the general Map contract and returns the
mapped value on remove() calls.
removeReturnsNull - true if you want ChronicleMap.remove() to not return the value of the removed entry
but instead return nullputReturnsNull(boolean)public ChronicleMapBuilder<K,V> maxBloatFactor(double maxBloatFactor)
ChronicleHashBuilder
ChronicleHashBuilder.entries(long) should represent the expected maximum number of entries in a stable
state, maxBloatFactor - the maximum bloat up coefficient, during exceptional bursts.
This configuration should be used for self-checking. Even if you configure impossibly
large maxBloatFactor, the created ChronicleHash, of cause, will be still
operational, and even won't allocate any extra resources before they are actually needed.
But when the ChronicleHash grows beyond the configured ChronicleHashBuilder.entries(long), it
could start to serve requests progressively slower. If you insert new entries into
ChronicleHash infinitely, due to a bug in your business logic code, or the
ChronicleHash configuration, and if you configure the ChronicleHash to grow infinitely, you
will have a terribly slow and fat, but operational application, instead of a fail with
IllegalStateException, which will quickly show you, that there is a bug in you
application.
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 ChronicleHashes completely differently,
or this data store doesn't fit to your case.
maxBloatFactor in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>maxBloatFactor - the maximum number ot times, the created hash container is supposed
to bloat up beyond the ChronicleHashBuilder.entries(long)ChronicleHashBuilder.entries(long)public double maxBloatFactor()
public ChronicleMapBuilder<K,V> allowSegmentTiering(boolean allowSegmentTiering)
ChronicleHashBuildermaxBloatFactor(1.0), that does not
guarantee that segments won't tier (due to bad hash distribution or natural variance),
configuring allowSegmentTiering(false) makes Chronicle Hashes, created by this
builder, to throw IllegalStateException immediately when some segment overflows.
Useful exactly for testing hash distribution and variance of segment filling.
Default is true, segments are allowed to tier.
When configured to false, ChronicleHashBuilder.maxBloatFactor(double) configuration becomes
irrelevant, because effectively no bloat is allowed.
allowSegmentTiering in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>allowSegmentTiering - if true, when a segment overflows a next tier
is allocated to accommodate new entriespublic ChronicleMapBuilder<K,V> nonTieredSegmentsPercentile(double nonTieredSegmentsPercentile)
ChronicleHashBuilderChronicleHashBuilder.entries(long), assuming hash code distribution of the keys, inserted
into configured Chronicle Hash, is good.
The last caveat means that the configured percentile and affects segment size relying on Poisson distribution law, if inserted entries (keys) fall into all segments randomly. If e. g. the keys, inserted into the Chronicle Hash, are purposely selected to collide by a certain range of hash code bits, so that they all fall into the same segment (a DOS attacker might do this), this segment is obviously going to be tiered.
This configuration affects the actual number of segments, if ChronicleHashBuilder.entries(long) and
ChronicleHashBuilder.entriesPerSegment(long) or ChronicleHashBuilder.actualChunksPerSegmentTier(long) are configured.
It affects the actual number of entries per segment/chunks per segment tier, if ChronicleHashBuilder.entries(long) and ChronicleHashBuilder.actualSegments(int) are configured. If all 4 configurations,
mentioned in this paragraph, are specified, nonTieredSegmentsPercentile doesn't make
any effect.
Default value is 0.99999, i. e. if hash code distribution of the keys is good, only one segment of 100K is tiered on average. If your segment size is small and you want to improve memory footprint of Chronicle Hash (probably compromising latency percentiles), you might want to configure more "relaxed" value, e. g. 0.99.
nonTieredSegmentsPercentile in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>nonTieredSegmentsPercentile - Fraction of segments which shouldn't be tieredpublic ChronicleMapBuilder<K,V> keyReaderAndDataAccess(SizedReader<K> keyReader, @NotNull DataAccess<K> keyDataAccess)
ChronicleHashBuilderDataAccess and SizedReader used to serialize and deserialize
keys to and from off-heap memory in hash containers, created by this builder.keyReaderAndDataAccess in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>keyReader - the new bytes → key object reader strategykeyDataAccess - the new strategy of accessing the keys' bytes for writingChronicleHashBuilder.keyMarshallers(SizedReader, SizedWriter)public ChronicleMapBuilder<K,V> keyMarshallers(@NotNull SizedReader<K> keyReader, @NotNull SizedWriter<? super K> keyWriter)
ChronicleHashBuilderkeyMarshallers in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>keyReader - the new bytes → key object reader strategykeyWriter - the new key object → bytes writer strategyChronicleHashBuilder.keyReaderAndDataAccess(SizedReader, DataAccess)public <M extends SizedReader<K> & SizedWriter<? super K>> ChronicleMapBuilder<K,V> keyMarshaller(@NotNull M sizedMarshaller)
ChronicleHashBuilderkeyMarshallers(sizedMarshaller, sizedMarshaller).keyMarshaller in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>sizedMarshaller - implementation of both SizedReader and SizedWriter
interfacespublic ChronicleMapBuilder<K,V> keyMarshallers(@NotNull BytesReader<K> keyReader, @NotNull BytesWriter<? super K> keyWriter)
ChronicleHashBuilderkeyMarshallers in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>keyReader - the new bytes → key object reader strategykeyWriter - the new key object → bytes writer strategyChronicleHashBuilder.keyReaderAndDataAccess(SizedReader, DataAccess)public <M extends BytesReader<K> & BytesWriter<? super K>> ChronicleMapBuilder<K,V> keyMarshaller(@NotNull M marshaller)
ChronicleHashBuilderkeyMarshallers(marshaller, marshaller).keyMarshaller in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>public ChronicleMapBuilder<K,V> keySizeMarshaller(@NotNull SizeMarshaller keySizeMarshaller)
ChronicleHashBuilder
Default key size marshaller is so-called "stop bit encoding" marshalling. If constant key size is configured, or defaulted if the key
type is always constant and ChronicleHashBuilder implementation knows about it, this
configuration takes no effect, because a special SizeMarshaller implementation, which
doesn't actually do any marshalling, and just returns the known constant size on SizeMarshaller.readSize(Bytes) calls, is used instead of any SizeMarshaller
configured using this method.
keySizeMarshaller in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>keySizeMarshaller - the new marshaller, used to serialize actual key sizes to off-heap
memorypublic ChronicleMapBuilder<K,V> aligned64BitMemoryOperationsAtomic(boolean aligned64BitMemoryOperationsAtomic)
ChronicleHashBuilderOS.is64Bit().aligned64BitMemoryOperationsAtomic in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>aligned64BitMemoryOperationsAtomic - true if aligned 8-byte memory operations
are atomicpublic ChronicleMapBuilder<K,V> checksumEntries(boolean checksumEntries)
ChronicleHashBuilder
By default, persisted hash containers, created by
ChronicleMapBuilder do compute and store entry checksums, but hash containers,
created in the process memory via ChronicleHashBuilder.create() - don't.
checksumEntries in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>checksumEntries - if entry checksums should be computed and storedChecksumEntry,
ChronicleHashBuilder.recoverPersistedTo(File, boolean)public ChronicleMapBuilder<K,V> valueReaderAndDataAccess(SizedReader<V> valueReader, @NotNull DataAccess<V> valueDataAccess)
DataAccess and SizedReader used to serialize and deserialize
values to and from off-heap memory in maps, created by this builder.valueReader - the new bytes → value object reader strategyvalueDataAccess - the new strategy of accessing the values' bytes for writingvalueMarshallers(SizedReader, SizedWriter),
ChronicleHashBuilder.keyReaderAndDataAccess(SizedReader, DataAccess)public ChronicleMapBuilder<K,V> valueMarshallers(@NotNull SizedReader<V> valueReader, @NotNull SizedWriter<? super V> valueWriter)
valueReader - the new bytes → value object reader strategyvalueWriter - the new value object → bytes writer strategyvalueReaderAndDataAccess(SizedReader, DataAccess),
valueSizeMarshaller(SizeMarshaller),
ChronicleHashBuilder.keyMarshallers(SizedReader, SizedWriter)public <M extends SizedReader<V> & SizedWriter<? super V>> ChronicleMapBuilder<K,V> valueMarshaller(@NotNull M sizedMarshaller)
valueMarshallers(sizedMarshaller, sizedMarshaller).public ChronicleMapBuilder<K,V> valueMarshallers(@NotNull BytesReader<V> valueReader, @NotNull BytesWriter<? super V> valueWriter)
valueReader - the new bytes → value object reader strategyvalueWriter - the new value object → bytes writer strategyvalueReaderAndDataAccess(SizedReader, DataAccess),
valueSizeMarshaller(SizeMarshaller),
ChronicleHashBuilder.keyMarshallers(BytesReader, BytesWriter)public <M extends BytesReader<V> & BytesWriter<? super V>> ChronicleMapBuilder<K,V> valueMarshaller(@NotNull M marshaller)
valueMarshallers(marshaller, marshaller).public ChronicleMapBuilder<K,V> valueSizeMarshaller(@NotNull SizeMarshaller valueSizeMarshaller)
Default value size marshaller is so-called "stop bit encoding" marshalling, unless constantValueSizeBySample(Object) or the builder statically knows the value size is
constant -- special constant size marshalling is used by default in these cases.
valueSizeMarshaller - the new marshaller, used to serialize actual value sizes to
off-heap memorykeySizeMarshaller(SizeMarshaller)public ChronicleMapBuilder<K,V> defaultValueProvider(@NotNull DefaultValueProvider<K,V> defaultValueProvider)
acquireUsing() calls, if the key is absent in the map, created by this builder.
This is a JVM-level configuration.
defaultValueProvider - the strategy to obtain a default value by the absent keypublic ChronicleMapBuilder<K,V> replication(byte identifier)
public ChronicleMapBuilder<K,V> replicatedMapClassName(String replicatedMapClassName)
public ChronicleMap<K,V> createPersistedTo(File file) throws IOException
ChronicleHashBuilder
Multiple containers could give access to the same data simultaneously, either inside a single JVM or across processes. Access is synchronized correctly across all instances, i. e. hash container mapping the data from the first JVM isn't able to modify the data, concurrently accessed from the second JVM by another hash container instance, mapping the same data.
On container's close() the data isn't removed, it remains on
disk and available to be opened again (given the same file name) or during different JVM
run.
This method is shortcut for instance().persistedTo(file).create().
createPersistedTo in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>file - the file with existing hash container or a desired location of a new off-heap
persisted hash containerIOException - if any IO error, related to off-heap memory allocation or file mapping,
or establishing replication connections, occursChronicleHash.file(),
ChronicleHash.close(),
ChronicleHashBuilder.create(),
ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean),
ChronicleHashBuilder.recoverPersistedTo(File, boolean)public ChronicleMap<K,V> createOrRecoverPersistedTo(File file) throws IOException
ChronicleHashBuildercreateOrRecoverPersistedTo(file, true).
This method couldn't be used, if the Chronicle Map was created using an older version
of the Chronicle Map library, and then createOrRecoverPersistedTo() is called with
a newer version of the Chronicle Map library. In this case, createOrRecoverPersistedTo(file, false) should
be used.
createOrRecoverPersistedTo in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>file - the persistence file for existing of future hash containerChronicleHash instance, mapped to the given instanceIOException - if any IO error occurs on reading data from the file, or related to
off-heap memory allocation or file mapping, or establishing replication connections. Probably
the file is corrupted on OS level, and should be recovered on that level first, before
calling this procedure.ChronicleHashBuilder.createPersistedTo(File),
ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean),
ChronicleHashBuilder.recoverPersistedTo(File, boolean),
ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean, ChronicleHashCorruption.Listener)public ChronicleMap<K,V> createOrRecoverPersistedTo(File file, boolean sameLibraryVersion) throws IOException
ChronicleHashBuilderChronicleHashBuilder.createPersistedTo(File), if the given
file doesn't exist, and recoverPersistedTo(file, sameLibraryVersion), if the file exists.
The difference between this method and ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean,
ChronicleHashCorruption.Listener) is that this method just logs the encountered corruptions,
instead of passing them to the specified corruption listener.
createOrRecoverPersistedTo in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>file - the persistence file for existing of future hash containersameLibraryVersion - if this builder is configured with the same configurations, as the
builder, which created the Chronicle Map in the given file initially, and the same version
of the Chronicle Map library was used. In this case, the header of the file is overridden
(with presumably the same configurations), protecting from ChronicleHashRecoveryFailedException, if the header is corrupted.ChronicleHash instance, mapped to the given instanceIOException - if any IO error occurs on reading data from the file, or related to
off-heap memory allocation or file mapping, or establishing replication connections. Probably
the file is corrupted on OS level, and should be recovered on that level first, before
calling this procedure.ChronicleHashBuilder.createPersistedTo(File),
ChronicleHashBuilder.recoverPersistedTo(File, boolean),
ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean, ChronicleHashCorruption.Listener)public ChronicleMap<K,V> createOrRecoverPersistedTo(File file, boolean sameLibraryVersion, ChronicleHashCorruption.Listener corruptionListener) throws IOException
ChronicleHashBuilderChronicleHashBuilder.createPersistedTo(File), if the given
file doesn't exist, and recoverPersistedTo(file, sameLibraryVersion, corruptionListener), if the file exists.
If this procedure encounters corruptions, it fixes them (recovers from them) and
notifies the provided corruption listener with the details about the corruption. See the
documentation for ChronicleHashCorruption for more information.
createOrRecoverPersistedTo in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>file - the persistence file for existing of future hash containersameLibraryVersion - if this builder is configured with the same configurations, as the
builder, which created the Chronicle Map in the given file initially, and the same version
of the Chronicle Map library was used. In this case, the header of the file is overridden
(with presumably the same configurations), protecting from ChronicleHashRecoveryFailedException, if the header is corrupted.ChronicleHash instance, mapped to the given instanceIOException - if any IO error occurs on reading data from the file, or related to
off-heap memory allocation or file mapping, or establishing replication connections. Probably
the file is corrupted on OS level, and should be recovered on that level first, before
calling this procedure.ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean),
ChronicleHashBuilder.recoverPersistedTo(File, boolean)public ChronicleMap<K,V> recoverPersistedTo(File file, boolean sameBuilderConfigAndLibraryVersion) throws IOException
ChronicleHashBuilder
This method, unlike ChronicleHashBuilder.createPersistedTo(File) or ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean) methods, expects that the given file already
exists.
"Recovery" of the hash container is changing the memory of the data structure so that
after the recovery the hash container is in some correct state: with "clean" locks, coherent
entry counters, not containing provably corrupt entries, etc. If checksumEntries(true) is configured for the chronicle hash
container, recovery procedure checks for each entry that the checksums is correct, otherwise
it assumes the entry is corrupt and deletes it from the Chronicle Hash. See the
Recovery section in the
Chronicle Map tutorial for more information.
The difference between this method and ChronicleHashBuilder.recoverPersistedTo(File, boolean,
ChronicleHashCorruption.Listener) is that this method just logs the encountered corruptions,
instead of passing them to the specified corruption listener.
At the moment this method is called and executed, no other thread or process should be
mapping to the given file, and trying to access the given file. Otherwise the outcomes of
the recoverPersistedTo() call, as well as the behaviour of the concurrent thread or
process, accessing the same Chronicle Map, are unspecified: exception or error could be
thrown, the Chronicle Map persisted to the given file could be further corrupted.
It is strongly recommended to configure this builder with the same configurations, as
the builder, that created the given file for the first time, and pass true as the
sameBuilderConfigAndLibraryVersion argument (another requirement is running
the same version of the Chronicle Map library). Otherwise, if the header of the given
persisted Chronicle Hash file is corrupted, this method is likely to be unable to recover and
throw ChronicleHashRecoveryFailedException, or even worse, to corrupt the file
further. Fortunately, the header should never be corrupted on an "ordinary" process
crash/termination or power loss, only on direct file corruption.
recoverPersistedTo in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>file - a hash container was mapped to the given filesameBuilderConfigAndLibraryVersion - if this builder is configured with the same
configurations, as the builder, which created the file (the persisted Chronicle Hash
instance) for the first time, and with the same version of the Chronicle Map library.
In this case, the header of the file is overridden (with presumably the same configurations),
protecting from ChronicleHashRecoveryFailedException, if the header is corrupted.FileNotFoundException - if the file doesn't existIOException - if any IO error occurs on reading data from the file, or related to
off-heap memory allocation or file mapping, or establishing replication connections. Probably
the file is corrupted on OS level, and should be recovered on that level first, before
calling this procedure.ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean),
ChronicleHashBuilder.createPersistedTo(File),
ChronicleHashBuilder.recoverPersistedTo(File, boolean, ChronicleHashCorruption.Listener)public ChronicleMap<K,V> recoverPersistedTo(File file, boolean sameBuilderConfigAndLibraryVersion, ChronicleHashCorruption.Listener corruptionListener) throws IOException
ChronicleHashBuilder
This method, unlike ChronicleHashBuilder.createPersistedTo(File) or ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean, ChronicleHashCorruption.Listener) methods,
expects that the given file already exists.
"Recovery" of the hash container is changing the memory of the data structure so that
after the recovery the hash container is in some correct state: with "clean" locks, coherent
entry counters, not containing provably corrupt entries, etc. If checksumEntries(true) is configured for the chronicle hash
container, recovery procedure checks for each entry that the checksums is correct, otherwise
it assumes the entry is corrupt and deletes it from the Chronicle Hash. See the
Recovery section in the
Chronicle Map tutorial for more information.
If this procedure encounters corruptions, it fixes them (recovers from them) and
notifies the provided corruption listener with the details about the corruption. See the
documentation for ChronicleHashCorruption for more information.
At the moment this method is called and executed, no other thread or process should be
mapping to the given file, and trying to access the given file. Otherwise the outcomes of
the recoverPersistedTo() call, as well as the behaviour of the concurrent thread or
process, accessing the same Chronicle Map, are unspecified: exception or error could be
thrown, the Chronicle Map persisted to the given file could be further corrupted.
recoverPersistedTo in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>file - a hash container was mapped to the given filesameBuilderConfigAndLibraryVersion - if this builder is configured with the same
configurations, as the builder, which created the file (the persisted Chronicle Hash
instance) for the first time, and with the same version of the Chronicle Map library.
In this case, the header of the file is overridden (with presumably the same configurations),
protecting from ChronicleHashRecoveryFailedException, if the header is corrupted.FileNotFoundException - if the file doesn't existIOException - if any IO error occurs on reading data from the file, or related to
off-heap memory allocation or file mapping, or establishing replication connections. Probably
the file is corrupted on OS level, and should be recovered on that level first, before
calling this procedure.ChronicleHashBuilder.recoverPersistedTo(File, boolean),
ChronicleHashBuilder.createOrRecoverPersistedTo(File, boolean, ChronicleHashCorruption.Listener),
ChronicleHashBuilder.createPersistedTo(File)public ChronicleMapBuilder<K,V> setPreShutdownAction(Runnable preShutdownAction)
ChronicleHashBuilderChronicleHash created using this builder is closed using a JVM shutdown hook.
This method lets you perform an action before the ChronicleHash is closed.
The registered action is not executed when JVM is running and a
ChronicleHash.close() is explicitly called.
Example usage of this call: To carry out a graceful shutdown and explicitly
control when the ChronicleHash is closed, the action can be a wait on a
CountDownLatch that would be released appropriately.
setPreShutdownAction in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>preShutdownAction - action to run before closing the ChronicleHash in a
JVM shutdown hook.public ChronicleMapBuilder<K,V> skipCloseOnExitHook(boolean skipCloseOnExitHook)
ChronicleHashBuilderChronicleHash created by
this builder. By setting this to true, the caller agrees to closing the built ChronicleHash
explicitly. Any pre-shutdown action configured via this#setPreShutdownAction(Runnable)
won't be executed if skipCloseOnExitHook is set to true.skipCloseOnExitHook in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>skipCloseOnExitHook - if true, default automatic close configuration is not enabled.public ChronicleMap<K,V> create()
ChronicleHashBuilderChronicleHash.close() called on the returned container, or
after the container object is collected during GC, or on JVM shutdown the off-heap memory
used by the returned container is freed.create in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>ChronicleHashBuilder.createPersistedTo(File)public ChronicleMapBuilder<K,V> entryOperations(MapEntryOperations<K,V,?> entryOperations)
ChronicleMap's operations with entries:
removing entries, replacing entries' value and inserting new entries.
This affects behaviour of ordinary map.put(), map.remove(), etc. calls, as well as removes and replacing values during iterations, remote map calls and internal replication operations.
This is a JVM-level configuration.
public ChronicleMapBuilder<K,V> mapMethods(MapMethods<K,V,?> mapMethods)
ChronicleMap's operations with individual keys:
from Map.containsKey(java.lang.Object) to ChronicleMap.acquireUsing(K, V) and
ConcurrentMap.merge(K, V, java.util.function.BiFunction<? super V, ? super V, ? extends V>).
This affects behaviour of ordinary map calls, as well as remote calls.
This is a JVM-level configuration.
Copyright © 2020. All rights reserved.