net.openhft.chronicle.map

Class OffHeapUpdatableChronicleMapBuilder<K,V>

java.lang.Object

net.openhft.chronicle.map.AbstractChronicleMapBuilder<K,V,OffHeapUpdatableChronicleMapBuilder<K,V>>

net.openhft.chronicle.map.OffHeapUpdatableChronicleMapBuilder<K,V>

All Implemented Interfaces:

Cloneable, ChronicleHashBuilder<K,ChronicleMap<K,V>,OffHeapUpdatableChronicleMapBuilder<K,V>>

public final class OffHeapUpdatableChronicleMapBuilder<K,V>
extends AbstractChronicleMapBuilder<K,V,OffHeapUpdatableChronicleMapBuilder<K,V>>

Method Summary

Methods

Modifier and Type	Method and Description
OffHeapUpdatableChronicleMapBuilder<K,V>	defaultValue(V defaultValue) Specifies the value to be put for each key queried in acquireUsing() method, if the key is absent in the map, created by this builder.
OffHeapUpdatableChronicleMapBuilder<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.
OffHeapUpdatableChronicleMapBuilder<K,V>	entryAndValueAlignment(Alignment alignment) Configures alignment strategy of address in memory of entries and independently of address in memory of values within entries in ChronicleMaps, created by this builder.
OffHeapUpdatableChronicleMapBuilder<K,V>	entrySize(int entrySize) Configures the size in bytes of allocation unit of hash container instances, created by this builder.
static <K,V> OffHeapUpdatableChronicleMapBuilder<K,V>	of(Class<K> keyClass, Class<V> valueClass)
OffHeapUpdatableChronicleMapBuilder<K,V>	prepareValueBytesOnAcquire(PrepareValueBytes<K,V> prepareValueBytes) Configures the procedure which is called on the bytes, which later the returned value is pointing to, if the key is absent, on acquireUsing() call on maps, created by this builder.

Methods inherited from class net.openhft.chronicle.map.AbstractChronicleMapBuilder

actualEntriesPerSegment, actualSegments, bytesMarshallerFactory, clone, constantKeySizeBySample, create, createPersistedTo, entries, equals, errorListener, eventListener, hashCode, immutableKeys, instance, keyDeserializationFactory, keyMarshaller, keyMarshallers, keySize, keySizeMarshaller, lockTimeOut, metaDataBytes, minSegments, objectSerializer, offHeapReference, putReturnsNull, removeReturnsNull, replication, replication, replication, statelessClient, timeProvider, toString, valueDeserializationFactory

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

of

public static <K,V> OffHeapUpdatableChronicleMapBuilder<K,V> of(@NotNull
                                                Class<K> keyClass,
                                                @NotNull
                                                Class<V> valueClass)

entrySize

public OffHeapUpdatableChronicleMapBuilder<K,V> entrySize(int entrySize)

Configures the size in bytes of allocation unit of hash container instances, created by this builder.

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 entry size is a minimum allocation portion in the hash containers, created by this builder. E. g. if entry 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. To minimize memory overuse and improve speed, you should pay decent attention to this configuration.

There are three major patterns of this configuration usage:

1. Key (and value, in ChronicleMap case) sizes are constant. Configure them via ChronicleHashBuilder.constantKeySizeBySample(Object) and ChronicleMapBuilder.constantValueSizeBySample(Object) methods, and you will experience no memory waste at all.
2. Key (and/or value size, in ChronicleMap case) varies moderately. Specify them using corresponding methods, or specify entry size directly by calling this method, by sizes somewhere between average and maximum possible. The idea is to have most (90% or more) entries to fit a single "entry size" with moderate memory waste (10-20% on average), rest 10% or less of entries should take 2 "entry sizes", thus with ~50% memory overuse.
3. Key (and/or value size, in ChronicleMap case) varies in a wide range. Then it's best to use entry size configuration in chunk mode. Specify entry size so that most entries should take from 5 to several dozens of "chunks". With this approach, average memory waste should be very low.

   However, remember that

   • Operations with entries that span several "entry sizes" are a bit slower, than entries which take a single "entry size". That is why "chunk" approach is not recommended, when key (and/or value size) varies moderately.
   • The maximum number of chunks could be taken by an entry is 64. IllegalArgumentException is thrown on attempt to insert too large entry, compared to the configured or computed entry size.
   • The number of "entries" in the whole map and per segment is actually the number "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 entry size of 50 * (8 bytes for each id) = 400 bytes would be a good choice:

   Map<Long, long[]> socialGraph = ChronicleMapBuilder
        .of(Long.class, long[].class)
        // given that graph should have of 1 billion nodes, and 150 average adjacency list size
        // => values takes 3 chuncks on average
        .entries(1_000_000_000L * (150 / 50))
        .entrySize(50 * 8)
        .create();

   It is minimum possible (because 3000 friends / 50 friends = 60 is close to 64 "max chunks by single entry" limit, and ensures moderate average memory overuse (not more than 20%).

In fully default case you can expect entry size to be about 256 bytes. But it is strongly recommended always to configure key size and value size, if they couldn't be derived statically.

If entry size is not configured explicitly by calling this method, it is computed based on meta data bytes, plus key size, plus value size, plus a few bytes required by implementations.

With respect to alignment.

Note that the actual entrySize will be aligned to 4 (default entry alignment). I. e. if you set entry size to 30, and entry alignment is set to Alignment.OF_4_BYTES, the actual entry size will be 32 (30 aligned to 4 bytes).

Specified by:

entrySize in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,OffHeapUpdatableChronicleMapBuilder<K,V>>

Overrides:

entrySize in class AbstractChronicleMapBuilder<K,V,OffHeapUpdatableChronicleMapBuilder<K,V>>

Parameters:

entrySize - the "chunk size" in bytes

Returns:

this builder back

See Also:

entryAndValueAlignment(Alignment), AbstractChronicleMapBuilder.entries(long)

entryAndValueAlignment

public OffHeapUpdatableChronicleMapBuilder<K,V> entryAndValueAlignment(Alignment alignment)

Configures alignment strategy of address in memory of entries and independently of address in memory of values within entries in ChronicleMaps, created by this builder.

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.

Note that entry size will be aligned according to this alignment. I. e. if you set entrySize(20) and Alignment.OF_8_BYTES, actual entry size will be 24 (20 aligned to 8 bytes).

Default is Alignment.OF_4_BYTES for Byteable values.

Parameters:

alignment - the new alignment of the maps constructed by this builder

Returns:

this ChronicleMapBuilder back

defaultValue

public OffHeapUpdatableChronicleMapBuilder<K,V> defaultValue(V defaultValue)

Specifies the value to be put for each key queried in acquireUsing() method, if the key is absent in the map, created by this builder.

This configuration overrides any previous AbstractChronicleMapBuilder.defaultValueProvider(DefaultValueProvider) configuration to this AbstractChronicleMapBuilder.

Also, it overrides any previous prepareValueBytesOnAcquire(net.openhft.chronicle.map.PrepareValueBytes<K, V>) configuration to this OffHeapUpdatableChronicleMapBuilder.

By default, the default value is not specified, default prepare value bytes routine is specified instead.

Overrides:

defaultValue in class AbstractChronicleMapBuilder<K,V,OffHeapUpdatableChronicleMapBuilder<K,V>>

Parameters:

defaultValue - the default value to be put to the map for absent keys during acquireUsing() calls

Returns:

this builder object back

See Also:

defaultValueProvider(DefaultValueProvider), prepareValueBytesOnAcquire(PrepareValueBytes)

defaultValueProvider

public OffHeapUpdatableChronicleMapBuilder<K,V> defaultValueProvider(@NotNull
                                                            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.

This configuration overrides any previous AbstractChronicleMapBuilder.defaultValue(Object) configuration to this AbstractChronicleMapBuilder.

Also, it overrides any previous prepareValueBytesOnAcquire(net.openhft.chronicle.map.PrepareValueBytes<K, V>) configuration to this OffHeapUpdatableChronicleMapBuilder.

By default, the default value provider is not specified, default prepare value bytes routine is specified instead.

Overrides:

defaultValueProvider in class AbstractChronicleMapBuilder<K,V,OffHeapUpdatableChronicleMapBuilder<K,V>>

Parameters:

defaultValueProvider - the strategy to obtain a default value by the absent key

Returns:

this builder object back

See Also:

defaultValue(Object), prepareValueBytesOnAcquire(PrepareValueBytes)

prepareValueBytesOnAcquire

public OffHeapUpdatableChronicleMapBuilder<K,V> prepareValueBytesOnAcquire(@NotNull
                                                                  PrepareValueBytes<K,V> prepareValueBytes)

Configures the procedure which is called on the bytes, which later the returned value is pointing to, if the key is absent, on acquireUsing() call on maps, created by this builder. See PrepareValueBytes for more information.

The default preparation callback zeroes out the value bytes.

Parameters:

prepareValueBytes - what to do with the value bytes before assigning them into the Byteable value to return from acquireUsing() call

Returns:

this builder back

See Also:

PrepareValueBytes, defaultValue(Object), defaultValueProvider(DefaultValueProvider)