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 addReplicator(Replicator replicator);
B setReplicators(Replicator... replicators);
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;
}