Alawn/Chronicle-Map
1
0
Fork 0
mirror of https://github.com/OpenHFT/Chronicle-Map.git synced 2021-09-13 01:26:12 +00:00
Code Releases Activity

HCOLL-218 ReplicatedChronicleMapTest appears to use too much resources - I've looked at other tests as well and have attempted to ensure that close is called on every test, also prompting the GC to run after each test.

Browse Source
This commit is contained in:
Rob Austin
2014-11-26 16:24:57 +00:00
parent f3161e31bb
commit 84a9581c7f
31 changed files with 844 additions and 857 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/main/java/net/openhft/chronicle/hash/ChronicleHashBuilder.java
+191 -167
View File
@@ -45,32 +45,36 @@ import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.TimeUnit;
/**
* This interface defines the meaning of configurations, common to {@link net.openhft.chronicle.map.OnHeapUpdatableChronicleMapBuilder}
* and {@link ChronicleSetBuilder}, i. e. <i>Chronicle hash container</i> configurations.
* This interface defines the meaning of configurations, common to {@link
* net.openhft.chronicle.map.OnHeapUpdatableChronicleMapBuilder} and {@link ChronicleSetBuilder}, i.
* e. <i>Chronicle hash container</i> configurations.
*
* <p>{@code ChronicleHashBuilder} is mutable. Configuration methods mutate the builder and return <i>the
* builder itself</i> back to support chaining pattern, rather than the builder copies with the corresponding
* configuration changed. To make an independent configuration, {@linkplain #clone} the builder.
* <p>{@code ChronicleHashBuilder} is mutable. Configuration methods mutate the builder and return
* <i>the builder itself</i> back to support chaining pattern, rather than the builder copies with
* the corresponding configuration changed. To make an independent configuration, {@linkplain
* #clone} the builder.
*
* @param <K> the type of keys in hash containers, created by this builder
* @param <C> the container type, created by this builder, i. e. {@link ChronicleMap} or {@link ChronicleSet}
* @param <B> the concrete builder type, i. e. {@link net.openhft.chronicle.map.ChronicleMapOnHeapUpdatableBuilder}
* @param <C> the container type, created by this builder, i. e. {@link ChronicleMap} or {@link
* ChronicleSet}
* @param <B> the concrete builder type, i. e. {@link net.openhft.chronicle.map.ChronicleMapBuilder}
* or {@link ChronicleSetBuilder}
*/
public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B extends ChronicleHashBuilder<K, C, B>> extends Cloneable {
/**
* Clones this builder. Useful for configuration persisting, because {@code ChronicleHashBuilder}s are
* mutable and changed on each configuration method call. Original and cloned builders are independent.
* Clones this builder. Useful for configuration persisting, because {@code
* ChronicleHashBuilder}s are mutable and changed on each configuration method call. Original
* and cloned builders are independent.
*
* @return a new clone of this builder
*/
B clone();
/**
* Set minimum number of segments in hash containers, constructed by this builder. See concurrencyLevel in
* {@link ConcurrentHashMap}.
* Set minimum number of segments in hash containers, constructed by this builder. See
* concurrencyLevel in {@link ConcurrentHashMap}.
*
* @param minSegments the minimum number of segments in containers, constructed by this builder
* @return this builder object back
@@ -78,13 +82,14 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B minSegments(int minSegments);
/**
* Configures the optimal number of bytes, taken by serialized form of keys, put into hash containers,
* created by this builder. If key size is always the same, call {@link #constantKeySizeBySample(Object)}
* method instead of this one.
* Configures the optimal number of bytes, taken by serialized form of keys, put into hash
* containers, created by this builder. If key size is always the same, call {@link
* #constantKeySizeBySample(Object)} method instead of this one.
*
* <p>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.
* <p>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
@@ -94,15 +99,15 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
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.
* 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.
*
* <p>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.
* <p>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.
*
* <p>If key size varies, method {@link #keySize(int)} or {@link #entrySize(int)} should be called instead
* of this one.
* <p>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
@@ -111,42 +116,44 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B constantKeySizeBySample(K sampleKey);
/**
* Configures the size in bytes of allocation unit of hash container instances, created by this builder.
* Configures the size in bytes of allocation unit of hash container instances, created by this
* builder.
*
* <p>{@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 <i>entry size</i> 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.
* <p>{@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 <i>entry size</i> 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.
*
* <p>There are three major patterns of this configuration usage: <ol> <li>Key (and value, in {@code
* ChronicleMap} case) sizes are constant. Configure them via {@link #constantKeySizeBySample(Object)} and
* {@link net.openhft.chronicle.map.OnHeapUpdatableChronicleMapBuilder#constantValueSizeBySample(Object)}
* methods, and you will experience no memory waste at all.</li> <li>Key (and/or value size, in {@code
* 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.</li>
* <li>Key (and/or value size, in {@code ChronicleMap} case) varies in a wide range. Then it's best to use
* entry size configuration in <i>chunk mode</i>. 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.
* <p>There are three major patterns of this configuration usage: <ol> <li>Key (and value, in
* {@code ChronicleMap} case) sizes are constant. Configure them via {@link
* #constantKeySizeBySample(Object)} and {@link net.openhft.chronicle.map.OnHeapUpdatableChronicleMapBuilder#constantValueSizeBySample(Object)}
* methods, and you will experience no memory waste at all.</li> <li>Key (and/or value size, in
* {@code 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.</li> <li>Key (and/or value size, in {@code
* ChronicleMap} case) varies in a wide range. Then it's best to use entry size configuration in
* <i>chunk mode</i>. 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.
*
* <p>However, remember that <ul> <li>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.</li> <li>The maximum number of chunks could be taken by
* an entry is 64. {@link IllegalArgumentException} is thrown on attempt to insert too large entry,
* compared to the configured or computed entry size.</li> <li>The number of "entries" {@linkplain
* #entries(long) in the whole map} and {@linkplain #actualEntriesPerSegment(long) per segment} is
* actually the number "chunks".</li> </ul>
* <p>However, remember that <ul> <li>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.</li> <li>The maximum
* number of chunks could be taken by an entry is 64. {@link IllegalArgumentException} is thrown
* on attempt to insert too large entry, compared to the configured or computed entry size.</li>
* <li>The number of "entries" {@linkplain #entries(long) in the whole map} and {@linkplain
* #actualEntriesPerSegment(long) per segment} is actually the number "chunks".</li> </ul>
*
* <p>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
* <p>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: <pre>{@code
* Map<Long, long[]> socialGraph = ChronicleMapOnHeapUpdatableBuilder
* .of(Long.class, long[].class)
@@ -155,8 +162,9 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
* .entries(1_000_000_000L * (150 / 50))
* .entrySize(50 * 8)
* .create();}</pre>
* 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%). </li> </ol>
* 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%). </li>
* </ol>
*
* @param entrySize the "chunk size" in bytes
* @return this builder back
@@ -165,29 +173,33 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B entrySize(int entrySize);
/**
* Configures the maximum number of {@linkplain #entrySize(int) "entry size chunks"}, which could be taken
* by the maximum number of entries, inserted into the hash containers, created by this builder. If you
* try to insert more data, {@link IllegalStateException} might be thrown, because currently {@link
* ChronicleMap} and {@link ChronicleSet} doesn't support resizing.
* Configures the maximum number of {@linkplain #entrySize(int) "entry size chunks"}, which
* could be taken by the maximum number of entries, inserted into the hash containers, created
* by this builder. If you try to insert more data, {@link IllegalStateException} might be
* thrown, because currently {@link ChronicleMap} and {@link ChronicleSet} doesn't support
* resizing.
*
* <ol> <li>If key size (and value size, in {@code ChronicleMap} case) is constant, this number is equal
* to the maximum number of entries (because each entry takes exactly one "entry size" memory unit).</li>
* <li>If key (and/or value, in {@code ChronicleMap} case) size varies moderately, you should pass to this
* method the maximum number of entries + 5-25%, depending on your data properties and configured
* {@linkplain #keySize(int) key}/{@linkplain net.openhft.chronicle.map.OnHeapUpdatableChronicleMapBuilder#valueSize(int)
* value}/{@linkplain #entrySize(int) entry} sizes.</li> <li>If your data size varies in a wide range,
* pass the maximum number of entries multiplied by average data size and divided by the configured "entry
* size" (i. e. chunk size). See an example in the documentation to {@link #entrySize(int)} method.</li>
* </ol>
* <ol> <li>If key size (and value size, in {@code ChronicleMap} case) is constant, this number
* is equal to the maximum number of entries (because each entry takes exactly one "entry size"
* memory unit).</li> <li>If key (and/or value, in {@code ChronicleMap} case) size varies
* moderately, you should pass to this method the maximum number of entries + 5-25%, depending
* on your data properties and configured {@linkplain #keySize(int) key}/{@linkplain
* net.openhft.chronicle.map.OnHeapUpdatableChronicleMapBuilder#valueSize(int)
* value}/{@linkplain #entrySize(int) entry} sizes.</li> <li>If your data size varies in a wide
* range, pass the maximum number of entries multiplied by average data size and divided by the
* configured "entry size" (i. e. chunk size). See an example in the documentation to {@link
* #entrySize(int)} method.</li> </ol>
*
* <p>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.
* <p>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.
*
* <p>Default value is 2^20 (~ 1 million).
*
* @param entries maximum size of the created maps, in memory allocation units, so-called "entry size"
* @param entries maximum size of the created maps, in memory allocation units, so-called "entry
* size"
* @return this builder back
* @see #entrySize(int)
*/
@@ -198,17 +210,18 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B actualSegments(int actualSegments);
/**
* Configures timeout of locking on {@linkplain #actualSegments(int) segments} of hash containers, created
* by this builder, when performing any queries, as well as bulk operations like iteration. If timeout
* expires, {@link ChronicleHashErrorListener#onLockTimeout(long)} is called, and then thread tries to
* obtain the segment lock one more time, and so in a loop, until thread is interrupted. However, you can
* configure {@linkplain #errorListener(ChronicleHashErrorListener) error listener} to throw an exception
* on the first (or n-th) lock acquisition fail.
* Configures timeout of locking on {@linkplain #actualSegments(int) segments} of hash
* containers, created by this builder, when performing any queries, as well as bulk operations
* like iteration. If timeout expires, {@link ChronicleHashErrorListener#onLockTimeout(long)} is
* called, and then thread tries to obtain the segment lock one more time, and so in a loop,
* until thread is interrupted. However, you can configure {@linkplain
* #errorListener(ChronicleHashErrorListener) error listener} to throw an exception on the first
* (or n-th) lock acquisition fail.
*
* <p>Default lock time out is 2 seconds.
*
* @param lockTimeOut new lock timeout for segments of containers created by this builder, in the given
* time units
* @param lockTimeOut new lock timeout for segments of containers created by this builder, in
* the given time units
* @param unit time unit of the given lock timeout
* @return this builder back
*/
@@ -219,8 +232,8 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B metaDataBytes(int metaDataBytes);
/**
* Configures a time provider, used by hash containers, created by this builder, for needs of replication
* consensus protocol (conflicting data updates resolution).
* Configures a time provider, used by hash containers, created by this builder, for needs of
* replication consensus protocol (conflicting data updates resolution).
*
* <p>Default time provider is {@link TimeProvider#SYSTEM}.
*
@@ -231,15 +244,17 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B timeProvider(TimeProvider timeProvider);
/**
* Configures a {@link BytesMarshallerFactory} to be used with {@link BytesMarshallableSerializer}, which
* is a default {@link #objectSerializer ObjectSerializer}, to serialize/deserialize data to/from off-heap
* memory in hash containers, created by this builder.
* Configures a {@link BytesMarshallerFactory} to be used with {@link
* BytesMarshallableSerializer}, which is a default {@link #objectSerializer ObjectSerializer},
* to serialize/deserialize data to/from off-heap memory in hash containers, created by this
* builder.
*
* <p>Default {@code BytesMarshallerFactory} is an instance of {@link VanillaBytesMarshallerFactory}. This
* is a convenience configuration method, it has no effect on the resulting hash containers, if
* {@linkplain #keyMarshaller(BytesMarshaller) custom data marshallers} are configured, data types extends
* one of specific serialization interfaces, recognized by this builder (e. g. {@code Externalizable} or
* {@code BytesMarshallable}), or {@code ObjectSerializer} is configured.
* <p>Default {@code BytesMarshallerFactory} is an instance of {@link
* VanillaBytesMarshallerFactory}. This is a convenience configuration method, it has no effect
* on the resulting hash containers, if {@linkplain #keyMarshaller(BytesMarshaller) custom data
* marshallers} are configured, data types extends one of specific serialization interfaces,
* recognized by this builder (e. g. {@code Externalizable} or {@code BytesMarshallable}), or
* {@code ObjectSerializer} is configured.
*
* @param bytesMarshallerFactory the marshaller factory to be used with the default {@code
* ObjectSerializer}, i. e. {@code BytesMarshallableSerializer}
@@ -249,18 +264,18 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B bytesMarshallerFactory(BytesMarshallerFactory bytesMarshallerFactory);
/**
* Configures the serializer used to serialize/deserialize data to/from off-heap memory, when specified
* class doesn't implement a specific serialization interface like {@link Externalizable} or {@link
* BytesMarshallable} (for example, if data is loosely typed and just {@code Object} is specified as the
* data class), or nullable data, and if custom marshaller is not {@linkplain
* #keyMarshaller(BytesMarshaller) configured}, in hash containers, created by this builder. Please read
* {@link ObjectSerializer} docs for more info and available options.
* Configures the serializer used to serialize/deserialize data to/from off-heap memory, when
* specified class doesn't implement a specific serialization interface like {@link
* Externalizable} or {@link BytesMarshallable} (for example, if data is loosely typed and just
* {@code Object} is specified as the data class), or nullable data, and if custom marshaller is
* not {@linkplain #keyMarshaller(BytesMarshaller) configured}, in hash containers, created by
* this builder. Please read {@link ObjectSerializer} docs for more info and available options.
*
* <p>Default serializer is {@link BytesMarshallableSerializer}, configured with the specified or default
* {@link #bytesMarshallerFactory(BytesMarshallerFactory) BytesMarshallerFactory}.
* <p>Default serializer is {@link BytesMarshallableSerializer}, configured with the specified
* or default {@link #bytesMarshallerFactory(BytesMarshallerFactory) BytesMarshallerFactory}.
*
* @param objectSerializer the serializer used to serialize loosely typed or nullable data if custom
* marshaller is not configured
* @param objectSerializer the serializer used to serialize loosely typed or nullable data if
* custom marshaller is not configured
* @return this builder back
* @see #bytesMarshallerFactory(BytesMarshallerFactory)
* @see #keyMarshaller(BytesMarshaller)
@@ -268,8 +283,8 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B objectSerializer(ObjectSerializer objectSerializer);
/**
* Configures the {@code BytesMarshaller} used to serialize/deserialize keys to/from off-heap memory in
* hash containers, created by this builder. See <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the
* Configures the {@code BytesMarshaller} used to serialize/deserialize keys to/from off-heap
* memory in hash containers, created by this builder. See <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the
* section about serialization in ChronicleMap manual</a> for more information.
*
* @param keyMarshaller the marshaller used to serialize keys
@@ -280,15 +295,15 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B keyMarshaller(@NotNull BytesMarshaller<K> keyMarshaller);
/**
* Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in hash
* containers, created by this builder. See <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the
* Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in
* hash containers, created by this builder. See <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the
* section about serialization in ChronicleMap manual</a> for more information.
*
* <p>Configuring marshalling this way results to a little bit more compact in-memory layout of the map,
* comparing to a single interface configuration: {@link #keyMarshaller(BytesMarshaller)}.
* <p>Configuring marshalling this way results to a little bit more compact in-memory layout of
* the map, comparing to a single interface configuration: {@link #keyMarshaller(BytesMarshaller)}.
*
* <p>Passing {@link BytesInterop} (which is a subinterface of {@link BytesWriter}) as the first argument
* is supported, and even more advantageous from performance perspective.
* <p>Passing {@link BytesInterop} (which is a subinterface of {@link BytesWriter}) as the first
* argument is supported, and even more advantageous from performance perspective.
*
* @param keyWriter the new key object &rarr; {@link Bytes} writer (interop) strategy
* @param keyReader the new {@link Bytes} &rarr; key object reader strategy
@@ -298,53 +313,57 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B keyMarshallers(@NotNull BytesWriter<K> keyWriter, @NotNull BytesReader<K> keyReader);
/**
* Configures the marshaller used to serialize actual key sizes to off-heap memory in hash containers,
* created by this builder.
* Configures the marshaller used to serialize actual key sizes to off-heap memory in hash
* containers, created by this builder.
*
* <p>Default key size marshaller is so-called {@linkplain SizeMarshallers#stopBit() stop bit encoding
* marshalling}. If {@linkplain #constantKeySizeBySample(Object) constant key size} is configured, or
* defaulted if the key type is always constant and {@code ChronicleHashBuilder} implementation knows
* about it, this configuration takes no effect, because a special {@link SizeMarshaller} implementation,
* which doesn't actually do any marshalling, and just returns the known constant size on {@link
* SizeMarshaller#readSize(Bytes)} calls, is used instead of any {@code SizeMarshaller} configured using
* this method.
* <p>Default key size marshaller is so-called {@linkplain SizeMarshallers#stopBit() stop bit
* encoding marshalling}. If {@linkplain #constantKeySizeBySample(Object) constant key size} is
* configured, or defaulted if the key type is always constant and {@code ChronicleHashBuilder}
* implementation knows about it, this configuration takes no effect, because a special {@link
* SizeMarshaller} implementation, which doesn't actually do any marshalling, and just returns
* the known constant size on {@link SizeMarshaller#readSize(Bytes)} calls, is used instead of
* any {@code SizeMarshaller} configured using this method.
*
* @param keySizeMarshaller the new marshaller, used to serialize actual key sizes to off-heap memory
* @param keySizeMarshaller the new marshaller, used to serialize actual key sizes to off-heap
* memory
* @return this builder back
*/
B keySizeMarshaller(@NotNull SizeMarshaller keySizeMarshaller);
/**
* Configures factory which is used to create a new key instance, if key class is either {@link Byteable},
* {@link BytesMarshallable} or {@link Externalizable} subclass in maps, created by this builder. If
* {@linkplain #keyMarshaller(BytesMarshaller) custom key marshaller} is configured, this configuration is
* unused, because it is incapsulated in {@link BytesMarshaller#read(Bytes)} method (without provided
* instance to read the data into), i. e. it's is the user-side responsibility.
* Configures factory which is used to create a new key instance, if key class is either {@link
* Byteable}, {@link BytesMarshallable} or {@link Externalizable} subclass in maps, created by
* this builder. If {@linkplain #keyMarshaller(BytesMarshaller) custom key marshaller} is
* configured, this configuration is unused, because it is incapsulated in {@link
* BytesMarshaller#read(Bytes)} method (without provided instance to read the data into), i. e.
* it's is the user-side responsibility.
*
* <p>Default key deserialization factory is {@link NewInstanceObjectFactory}, which creates a new key
* instance using {@link Class#newInstance()} default constructor. You could provide an {@link
* AllocateInstanceObjectFactory}, which uses {@code Unsafe.allocateInstance(Class)} (you might want to do
* this for better performance or if you don't want to initialize fields), or a factory which calls a key
* class constructor with some arguments, or a factory which internally delegates to instance pool or
* {@link ThreadLocal}, to reduce allocations.
* <p>Default key deserialization factory is {@link NewInstanceObjectFactory}, which creates a
* new key instance using {@link Class#newInstance()} default constructor. You could provide an
* {@link AllocateInstanceObjectFactory}, which uses {@code Unsafe.allocateInstance(Class)} (you
* might want to do this for better performance or if you don't want to initialize fields), or a
* factory which calls a key class constructor with some arguments, or a factory which
* internally delegates to instance pool or {@link ThreadLocal}, to reduce allocations.
*
* @param keyDeserializationFactory the key factory used to produce instances to deserialize data in
* @param keyDeserializationFactory the key factory used to produce instances to deserialize
* data in
* @return this builder back
* @throws IllegalStateException if custom key marshaller is specified or key class is not either {@code
* Byteable}, {@code BytesMarshallable} or {@code Externalizable}
* @throws IllegalStateException if custom key marshaller is specified or key class is not
* either {@code Byteable}, {@code BytesMarshallable} or {@code
* Externalizable}
*/
B keyDeserializationFactory(@NotNull ObjectFactory<K> keyDeserializationFactory);
/**
* Specifies that key objects, queried with the hash containers, created by this builder, are inherently
* immutable. Keys in {@link ChronicleMap} or {@link ChronicleSet} are not required to be immutable, as in
* ordinary {@link Map} or {@link Set} implementations, because they are serialized off-heap. However,
* {@code ChronicleMap} and {@code ChronicleSet} implementations can benefit from the knowledge that keys
* are not mutated between queries.
* Specifies that key objects, queried with the hash containers, created by this builder, are
* inherently immutable. Keys in {@link ChronicleMap} or {@link ChronicleSet} are not required
* to be immutable, as in ordinary {@link Map} or {@link Set} implementations, because they are
* serialized off-heap. However, {@code ChronicleMap} and {@code ChronicleSet} implementations
* can benefit from the knowledge that keys are not mutated between queries.
*
* <p>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.
* <p>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
*/
@@ -352,13 +371,14 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
/**
* Configures replication of the hash containers, created by this builder. See <a
* href="https://github.com/OpenHFT/Chronicle-Map#tcp--udp-replication"> the section about replication in
* ChronicleMap manual</a> for more information.
* href="https://github.com/OpenHFT/Chronicle-Map#tcp--udp-replication"> the section about
* replication in ChronicleMap manual</a> for more information.
*
* <p>By default, hash containers, created by this builder doesn't replicate their data.
*
* <p>This method call overrides all previous replication configurations of this builder, made either by
* this method or {@link #replication(byte, TcpTransportAndNetworkConfig)} shortcut method.
* <p>This method call overrides all previous replication configurations of this builder, made
* either by this method or {@link #replication(byte, TcpTransportAndNetworkConfig)} shortcut
* method.
*
* @param replication the replication config
* @return this builder back
@@ -370,7 +390,8 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
/**
* Shortcut for {@code replication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier))}.
*
* @param identifier the network-wide identifier of the containers, created by this builder
* @param identifier the network-wide identifier of the containers, created by this
* builder
* @param tcpTransportAndNetwork configuration of tcp connection and network
* @return this builder back
* @see #replication(SingleChronicleHashReplication)
@@ -385,40 +406,43 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
ChronicleHashInstanceConfig<C> instance();
/**
* Creates a new hash container, storing it's data in off-heap memory, not mapped to any file. On {@link
* ChronicleHash#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.
* Creates a new hash container, storing it's data in off-heap memory, not mapped to any file.
* On {@link ChronicleHash#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.
*
* <p>This method is a shortcut for {@code instance().create()}.
*
* @return a new off-heap hash container
* @throws IOException if any IO error relates to off-heap memory allocation, or establishing replication
* connections, occurs
* @throws IOException if any IO error relates to off-heap memory allocation, or establishing
* replication connections, occurs
* @see #createPersistedTo(File)
* @see #instance()
*/
C create() throws IOException;
/**
* Opens a hash container residing the specified file, or creates a new one if the file not yet exists and
* maps its off-heap memory to the file. All changes to the map are persisted to disk (this is an
* operating system guarantee) independently from JVM process lifecycle.
* Opens a hash container residing the specified file, or creates a new one if the file not yet
* exists and maps its off-heap memory to the file. All changes to the map are persisted to disk
* (this is an operating system guarantee) independently from JVM process lifecycle.
*
* <p>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.
* <p>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.
*
* <p>On container's {@link ChronicleHash#close() 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.
* <p>On container's {@link ChronicleHash#close() 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.
*
* <p>This method is shortcut for {@code instance().persistedTo(file).create()}.
*
* @param file the file with existing hash container or a desired location of a new off-heap persisted
* hash container
* @param file the file with existing hash container or a desired location of a new off-heap
* persisted hash container
* @return a hash container mapped to the given file
* @throws IOException if any IO error, related to off-heap memory allocation or file mapping, or
* establishing replication connections, occurs
* @throws IOException if any IO error, related to off-heap memory allocation or file mapping,
* or establishing replication connections, occurs
* @see ChronicleHash#file()
* @see ChronicleHash#close()
* @see #create()
src/main/java/net/openhft/chronicle/set/ChronicleSetBuilder.java
+49 -48
View File
@@ -42,11 +42,11 @@ import java.net.InetSocketAddress;
import java.util.concurrent.TimeUnit;
/**
* {@code ChronicleSetBuilder} manages the whole set of {@link ChronicleSet} configurations, could be used as
* a classic builder and/or factory.
* {@code ChronicleSetBuilder} manages the whole set of {@link ChronicleSet} configurations, could
* be used as a classic builder and/or factory.
*
* <p>{@code ChronicleMapOnHeapUpdatableBuilder} is mutable, see a note in {@link ChronicleHashBuilder}
* interface documentation.
* <p>{@code ChronicleMapOnHeapUpdatableBuilder} is mutable, see a note in {@link
* ChronicleHashBuilder} interface documentation.
*
* @param <E> element type of the sets, created by this builder
* @see ChronicleSet
@@ -55,10 +55,10 @@ import java.util.concurrent.TimeUnit;
public class ChronicleSetBuilder<E>
implements ChronicleHashBuilder<E, ChronicleSet<E>, ChronicleSetBuilder<E>> {
private ChronicleMapBuilder<E, DummyValue> chronicleMapBuilderOnHeap;
private ChronicleMapBuilder<E, DummyValue> chronicleMapBuilder;
ChronicleSetBuilder(Class<E> keyClass) {
chronicleMapBuilderOnHeap = ChronicleMapBuilder.of(keyClass, DummyValue.class)
chronicleMapBuilder = ChronicleMapBuilder.of(keyClass, DummyValue.class)
.valueMarshallers(DummyValueMarshaller.INSTANCE, DummyValueMarshaller.INSTANCE)
.valueSizeMarshaller(DummyValueMarshaller.INSTANCE);
}
@@ -72,7 +72,7 @@ public class ChronicleSetBuilder<E>
try {
@SuppressWarnings("unchecked")
final ChronicleSetBuilder<E> result = (ChronicleSetBuilder<E>) super.clone();
result.chronicleMapBuilderOnHeap = chronicleMapBuilderOnHeap.clone();
result.chronicleMapBuilder = chronicleMapBuilder.clone();
return result;
} catch (CloneNotSupportedException e) {
throw new AssertionError(e);
@@ -81,19 +81,19 @@ public class ChronicleSetBuilder<E>
@Override
public ChronicleSetBuilder<E> actualSegments(int actualSegments) {
chronicleMapBuilderOnHeap.actualSegments(actualSegments);
chronicleMapBuilder.actualSegments(actualSegments);
return this;
}
@Override
public ChronicleSetBuilder<E> minSegments(int minSegments) {
chronicleMapBuilderOnHeap.minSegments(minSegments);
chronicleMapBuilder.minSegments(minSegments);
return this;
}
@Override
public ChronicleSetBuilder<E> actualEntriesPerSegment(long actualEntriesPerSegment) {
chronicleMapBuilderOnHeap.actualEntriesPerSegment(actualEntriesPerSegment);
chronicleMapBuilder.actualEntriesPerSegment(actualEntriesPerSegment);
return this;
}
@@ -107,16 +107,16 @@ public class ChronicleSetBuilder<E>
* .keySize(10)
* .create();}</pre>
*
* <p>(Note that 10 is chosen as key size in bytes despite strings in Java are UTF-16 encoded (and each
* character takes 2 bytes on-heap), because default off-heap {@link String} encoding is UTF-8 in {@code
* ChronicleSet}.)
* <p>(Note that 10 is chosen as key size in bytes despite strings in Java are UTF-16 encoded
* (and each character takes 2 bytes on-heap), because default off-heap {@link String} encoding
* is UTF-8 in {@code ChronicleSet}.)
*
* @see #constantKeySizeBySample(Object)
* @see #entrySize(int)
*/
@Override
public ChronicleSetBuilder<E> keySize(int keySize) {
chronicleMapBuilderOnHeap.keySize(keySize);
chronicleMapBuilder.keySize(keySize);
return this;
}
@@ -132,55 +132,55 @@ public class ChronicleSetBuilder<E>
*/
@Override
public ChronicleSetBuilder<E> constantKeySizeBySample(E sampleKey) {
chronicleMapBuilderOnHeap.constantKeySizeBySample(sampleKey);
chronicleMapBuilder.constantKeySizeBySample(sampleKey);
return this;
}
/**
* {@inheritDoc}
*
* <p>In fully default case you can expect entry size to be about 120-130 bytes. But it is strongly
* recommended always to configure {@linkplain #keySize(int) key size}, if they couldn't be derived
* statically.
* <p>In fully default case you can expect entry size to be about 120-130 bytes. But it is
* strongly recommended always to configure {@linkplain #keySize(int) key size}, if they
* couldn't be derived statically.
*
* <p>If entry size is not configured explicitly by calling this method, it is computed based on
* {@linkplain #metaDataBytes(int) meta data bytes}, plus {@linkplain #keySize(int) key size}, plus a few
* bytes required by implementations.
* {@linkplain #metaDataBytes(int) meta data bytes}, plus {@linkplain #keySize(int) key size},
* plus a few bytes required by implementations.
*/
@Override
public ChronicleSetBuilder<E> entrySize(int entrySize) {
chronicleMapBuilderOnHeap.entrySize(entrySize);
chronicleMapBuilder.entrySize(entrySize);
return this;
}
@Override
public ChronicleSetBuilder<E> entries(long entries) {
chronicleMapBuilderOnHeap.entries(entries);
chronicleMapBuilder.entries(entries);
return this;
}
@Override
public ChronicleSetBuilder<E> lockTimeOut(long lockTimeOut, TimeUnit unit) {
chronicleMapBuilderOnHeap.lockTimeOut(lockTimeOut, unit);
chronicleMapBuilder.lockTimeOut(lockTimeOut, unit);
return this;
}
@Override
public ChronicleSetBuilder<E> errorListener(ChronicleHashErrorListener errorListener) {
chronicleMapBuilderOnHeap.errorListener(errorListener);
chronicleMapBuilder.errorListener(errorListener);
return this;
}
@Override
public ChronicleSetBuilder<E> metaDataBytes(int metaDataBytes) {
chronicleMapBuilderOnHeap.metaDataBytes(metaDataBytes);
chronicleMapBuilder.metaDataBytes(metaDataBytes);
return this;
}
@Override
public String toString() {
return " ChronicleSetBuilder{" +
"chronicleMapBuilderOnHeap=" + chronicleMapBuilderOnHeap +
"chronicleMapBuilder=" + chronicleMapBuilder +
'}';
}
@@ -189,7 +189,7 @@ public class ChronicleSetBuilder<E>
public boolean equals(Object o) {
if (!(o instanceof ChronicleSetBuilder))
return false;
return chronicleMapBuilderOnHeap.equals(((ChronicleSetBuilder) o).chronicleMapBuilderOnHeap);
return chronicleMapBuilder.equals(((ChronicleSetBuilder) o).chronicleMapBuilder);
}
@Override
@@ -199,14 +199,14 @@ public class ChronicleSetBuilder<E>
@Override
public ChronicleSetBuilder<E> timeProvider(TimeProvider timeProvider) {
chronicleMapBuilderOnHeap.timeProvider(timeProvider);
chronicleMapBuilder.timeProvider(timeProvider);
return this;
}
@Override
public ChronicleSetBuilder<E> bytesMarshallerFactory(
BytesMarshallerFactory bytesMarshallerFactory) {
chronicleMapBuilderOnHeap.bytesMarshallerFactory(bytesMarshallerFactory);
chronicleMapBuilder.bytesMarshallerFactory(bytesMarshallerFactory);
return this;
}
@@ -222,102 +222,103 @@ public class ChronicleSetBuilder<E>
*/
@Override
public ChronicleSetBuilder<E> objectSerializer(ObjectSerializer objectSerializer) {
chronicleMapBuilderOnHeap.objectSerializer(objectSerializer);
chronicleMapBuilder.objectSerializer(objectSerializer);
return this;
}
@Override
public ChronicleSetBuilder<E> keyMarshaller(@NotNull BytesMarshaller<E> keyMarshaller) {
chronicleMapBuilderOnHeap.keyMarshaller(keyMarshaller);
chronicleMapBuilder.keyMarshaller(keyMarshaller);
return this;
}
@Override
public ChronicleSetBuilder<E> keyMarshallers(@NotNull BytesWriter<E> keyWriter,
@NotNull BytesReader<E> keyReader) {
chronicleMapBuilderOnHeap.keyMarshallers(keyWriter, keyReader);
chronicleMapBuilder.keyMarshallers(keyWriter, keyReader);
return this;
}
@Override
public ChronicleSetBuilder<E> keySizeMarshaller(@NotNull SizeMarshaller keySizeMarshaller) {
chronicleMapBuilderOnHeap.keySizeMarshaller(keySizeMarshaller);
chronicleMapBuilder.keySizeMarshaller(keySizeMarshaller);
return this;
}
/**
* {@inheritDoc}
*
* <p>Actually this is just a convenience method supporting key marshaller configurations, made initially
* during {@link #of(Class)} call. Because if you {@linkplain #keyMarshaller(BytesMarshaller) configure}
* own custom key marshaller, this method doesn't take any effect on the maps constructed by this
* builder.
* <p>Actually this is just a convenience method supporting key marshaller configurations, made
* initially during {@link #of(Class)} call. Because if you {@linkplain
* #keyMarshaller(BytesMarshaller) configure} own custom key marshaller, this method doesn't
* take any effect on the maps constructed by this builder.
*
* @see #of(Class)
*/
@Override
public ChronicleSetBuilder<E> keyDeserializationFactory(
@NotNull ObjectFactory<E> keyDeserializationFactory) {
chronicleMapBuilderOnHeap.keyDeserializationFactory(keyDeserializationFactory);
chronicleMapBuilder.keyDeserializationFactory(keyDeserializationFactory);
return this;
}
@Override
public ChronicleSetBuilder<E> immutableKeys() {
chronicleMapBuilderOnHeap.immutableKeys();
chronicleMapBuilder.immutableKeys();
return this;
}
@Override
public ChronicleSetBuilder<E> replication(SingleChronicleHashReplication replication) {
chronicleMapBuilderOnHeap.replication(replication);
chronicleMapBuilder.replication(replication);
return this;
}
@Override
public ChronicleSetBuilder<E> replication(byte identifier, TcpTransportAndNetworkConfig tcpTransportAndNetwork) {
chronicleMapBuilderOnHeap.replication(identifier, tcpTransportAndNetwork);
chronicleMapBuilder.replication(identifier, tcpTransportAndNetwork);
return this;
}
@Override
public ChronicleSetBuilder<E> replication(byte identifier) {
chronicleMapBuilderOnHeap.replication(identifier);
chronicleMapBuilder.replication(identifier);
return this;
}
@Override
public StatelessClientConfig<ChronicleSet<E>> statelessClient(
InetSocketAddress remoteAddress) {
return new StatelessSetConfig<>(chronicleMapBuilderOnHeap.statelessClient(remoteAddress));
return new StatelessSetConfig<>(chronicleMapBuilder.statelessClient(remoteAddress));
}
@Override
public ChronicleHashInstanceConfig<ChronicleSet<E>> instance() {
return new InstanceConfig<>(chronicleMapBuilderOnHeap.instance());
return new InstanceConfig<>(chronicleMapBuilder.instance());
}
@Override
public ChronicleSet<E> create() throws IOException {
final ChronicleMap<E, DummyValue> map = chronicleMapBuilderOnHeap.create();
final ChronicleMap<E, DummyValue> map = chronicleMapBuilder.create();
return new SetFromMap<E>(map);
}
@Override
public ChronicleSet<E> createPersistedTo(File file) throws IOException {
ChronicleMap<E, DummyValue> map = chronicleMapBuilderOnHeap.createPersistedTo(file);
ChronicleMap<E, DummyValue> map = chronicleMapBuilder.createPersistedTo(file);
return new SetFromMap<E>(map);
}
@Override
public String name() {
return chronicleMapBuilderOnHeap.name();
return chronicleMapBuilder.name();
}
public ChronicleSetBuilder<E> name(String name) {
chronicleMapBuilderOnHeap.name(name);
chronicleMapBuilder.name(name);
return this;
}
}