If key size varies moderately, specify the size higher than average, but lower than the maximum * possible, to minimize average memory overuse. If key size varies in a wide range, it's better to use * {@linkplain #entrySize(int) entry size} in "chunk" mode and configure it directly. * * @param keySize number of bytes, taken by serialized form of keys * @return this builder back * @see #constantKeySizeBySample(Object) * @see #entrySize(int) */ B keySize(int keySize); /** * Configures the constant number of bytes, taken by serialized form of keys, put into hash containers, * created by this builder. This is done by providing the {@code 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 {@link 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 {@link #keySize(int)} or {@link #entrySize(int)} should be called instead * of this one. * * @param sampleKey the sample key * @return this builder back * @see #keySize(int) */ B constantKeySizeBySample(K sampleKey); /** * Configures the size in bytes of allocation unit of hash container instances, created by this builder. * *
{@link ChronicleMap} and {@link ChronicleSet} store their data off-heap, so it is required to * serialize key (and values, in {@code ChronicleMap} case) (unless they are direct {@link Byteable} * instances). Serialized key bytes (+ serialized value bytes, in {@code ChronicleMap} case) + some * metadata bytes comprise "entry space", which {@code ChronicleMap} or {@code 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:
However, remember that
Example: if values in your {@code ChronicleMap} are adjacency lists of some social graph, where * nodes are represented as {@code long} ids, and adjacency lists are serialized in efficient manner, for * example as {@code 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:
{@code
* Map 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%). You shouldn't put additional margin over the number, computed according the rules above. This bad * practice was popularized by {@link HashMap#HashMap(int)} and {@link HashSet#HashSet(int)} constructors, * which accept "capacity", that should be multiplied by "load factor" to obtain actual maximum expected * number of entries. {@code ChronicleMap} and {@code ChronicleSet} don't have a notion of load factor. * *
Default value is 2^20 (~ 1 million).
*
* @param entries maximum size of the created maps, in memory allocation units, so-called "entry size"
* @return this builder back
* @see #entrySize(int)
*/
B entries(long entries);
B actualEntriesPerSegment(int actualEntriesPerSegment);
B actualSegments(int actualSegments);
B lockTimeOut(long lockTimeOut, TimeUnit unit);
B errorListener(ChronicleHashErrorListener errorListener);
B largeSegments(boolean largeSegments);
B metaDataBytes(int metaDataBytes);
B replicators(byte identifier, ReplicationConfig... replicators);
B channel(ChannelProvider.ChronicleChannel chronicleChannel);
B timeProvider(TimeProvider timeProvider);
B bytesMarshallerFactory(BytesMarshallerFactory bytesMarshallerFactory);
B objectSerializer(ObjectSerializer objectSerializer);
B keyMarshaller(@NotNull BytesMarshaller By default, {@code ChronicleHashBuilder}s detects immutability automatically only for very few
* standard JDK types (for example, for {@link String}), it is not recommended to rely on {@code
* ChronicleHashBuilder} to be smart enough about this.
*
* @return this builder back
*/
B immutableKeys();
C create(File file) throws IOException;
C create() throws IOException;
}