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-136 HCOLL-137 javadoc updates and added ChronicleHashBuilder.disableReplication() method

Browse Source
This commit is contained in:
leventov
2014-10-19 23:18:50 +04:00
parent c404c5cb75
commit 8f3452e974
6 changed files with 387 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/main/java/net/openhft/chronicle/ChronicleHashBuilder.java
+284 -85
View File
@@ -1,17 +1,14 @@
package net.openhft.chronicle;
import net.openhft.chronicle.map.ChannelProvider;
import net.openhft.chronicle.map.ChronicleMap;
import net.openhft.chronicle.map.ChronicleMapBuilder;
import net.openhft.chronicle.map.ReplicationConfig;
import net.openhft.chronicle.map.*;
import net.openhft.chronicle.set.ChronicleSet;
import net.openhft.chronicle.set.ChronicleSetBuilder;
import net.openhft.lang.io.serialization.BytesMarshaller;
import net.openhft.lang.io.serialization.BytesMarshallerFactory;
import net.openhft.lang.io.serialization.ObjectSerializer;
import net.openhft.lang.io.serialization.*;
import net.openhft.lang.io.serialization.impl.VanillaBytesMarshallerFactory;
import net.openhft.lang.model.Byteable;
import org.jetbrains.annotations.NotNull;
import java.io.Externalizable;
import java.io.File;
import java.io.IOException;
import java.util.HashMap;
@@ -22,20 +19,35 @@ import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.TimeUnit;
/**
* This interface defines the meaning of configurations, common to {@link ChronicleMapBuilder} and {@link
* ChronicleSetBuilder}, i. e. <i>Chronicle hash container</i> configurations.
* This interface defines the meaning of configurations, common to {@link ChronicleMapBuilder}
* 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.
*
* @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 ChronicleMapBuilder} or {@link ChronicleSetBuilder}
* @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 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.
*
* @return a new clone of this builder
*/
B clone();
/**
* Set minimum number of segments. 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
@@ -43,13 +55,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
@@ -59,15 +72,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
@@ -76,43 +89,55 @@ 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 ChronicleMapBuilder#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 ChronicleMapBuilder#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(int) 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(int) 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
* 50 * (8 bytes for each id) = 400 bytes would be a good choice: <pre>{@code
* <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 = ChronicleMapBuilder
* .of(Long.class, long[].class)
* // given that graph should have of 1 billion nodes, and 150 average adjacency list size
@@ -120,8 +145,11 @@ 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
@@ -130,28 +158,35 @@ 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 ChronicleMapBuilder#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
* ChronicleMapBuilder#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)
*/
@@ -161,6 +196,22 @@ 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.
*
* <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 unit time unit of the given lock timeout
* @return this builder back
*/
B lockTimeOut(long lockTimeOut, TimeUnit unit);
B errorListener(ChronicleHashErrorListener errorListener);
@@ -169,34 +220,182 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
B metaDataBytes(int metaDataBytes);
/**
* Configures replication of the hash containers, created by this builder (via independent
* replicators). See <a href="https://github.com/OpenHFT/Chronicle-Map#tcp--udp-replication">
* the section about replication in ChronicleMap manual</a> for more information.
*
* <p>Another way to establish replication is {@link #channel(ChannelProvider.ChronicleChannel)}
* method.
*
* <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 #channel(ChannelProvider.ChronicleChannel)} method.
*
* @param identifier the new {@linkplain Replica#identifier() identifier} of the containers,
* created by this builder
* @param replicators several replicators, used to sync the data across replicating nodes
* independently
* @return this builder back
* @see #channel(ChannelProvider.ChronicleChannel)
* @see #disableReplication()
*/
B replicators(byte identifier, ReplicationConfig... replicators);
/**
* Configures replication of the hash containers, created by this builder,
* via so called "channels". See <a
* href="https://github.com/OpenHFT/Chronicle-Map#channels-and-channelprovider">the section
* about Channels and ChannelProvider in ChronicleMap manual</a> for more information.
*
* <p>Another way to establish replication if {@link #replicators(byte, ReplicationConfig[])}
* method.
*
* <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 means of this method or {@link #replicators(byte, ReplicationConfig[])} method
* calls.
*
* @param chronicleChannel the channel responsible for gathering updates of hash containers,
* created by this builder, and replicating them over network
* @return this builder object back
* @see #replicators(byte, ReplicationConfig[])
* @see #disableReplication()
*/
B channel(ChannelProvider.ChronicleChannel chronicleChannel);
/**
* Specifies that hash containers, created by this builder, shouldn't replicate their data over
* network. This method call clears any replication configurations, made via {@link
* #replicators(byte, ReplicationConfig[])} or {@link #channel(
* ChannelProvider.ChronicleChannel)} method call.
*
* <p>By default replication is not configured, so this method is useful <i>only</i> to ensure
* that hash containers, created by some inherited or passed builder, wouldn't replicate. I. e.
* in rare cases.
*
* @return this builder back
* @see #replicators(byte, ReplicationConfig[])
* @see #channel(ChannelProvider.ChronicleChannel)
*/
B disableReplication();
/**
* 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}.
* @param timeProvider a new time provider for replication needs
* @return this builder back
* @see #replicators(byte, ReplicationConfig[])
* @see #channel(ChannelProvider.ChronicleChannel)
*/
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.
*
* <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}
* @return this builder back
* @see #objectSerializer(ObjectSerializer)
*/
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.
*
* <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
* @return this builder back
* @see #bytesMarshallerFactory(BytesMarshallerFactory)
* @see #keyMarshaller(BytesMarshaller)
*/
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 section about serialization
* in ChronicleMap manual</a> for more information.
*
* @param keyMarshaller the marshaller used to serialize keys
* @return this builder back
* @see #objectSerializer(ObjectSerializer)
*/
B keyMarshaller(@NotNull BytesMarshaller<K> keyMarshaller);
/**
* 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
*/
B immutableKeys();
/**
* 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>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.
*
* @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
* occurs
* @see ChronicleHash#file()
* @see ChronicleHash#close()
* @see #create()
*/
C create(File file) throws IOException;
/**
* 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.
*
* @return a new off-heap hash container
* @throws IOException if any IO error relates to off-heap memory allocation occurs
* @see #create()
*/
C create() throws IOException;
}
src/main/java/net/openhft/chronicle/map/ChronicleMap.java
-2
View File
@@ -24,8 +24,6 @@ import net.openhft.lang.io.serialization.ObjectFactory;
import net.openhft.lang.model.Byteable;
import java.io.Closeable;
import java.io.File;
import java.io.IOException;
import java.util.Map;
import java.util.concurrent.ConcurrentMap;
src/main/java/net/openhft/chronicle/map/ChronicleMapBuilder.java
+33 -3
View File
@@ -24,6 +24,7 @@ import net.openhft.chronicle.serialization.AgileBytesMarshaller;
import net.openhft.chronicle.serialization.MetaBytesInterop;
import net.openhft.chronicle.serialization.MetaBytesWriter;
import net.openhft.chronicle.serialization.MetaProvider;
import net.openhft.chronicle.set.ChronicleSetBuilder;
import net.openhft.chronicle.threadlocal.Provider;
import net.openhft.chronicle.threadlocal.ThreadLocalCopies;
import net.openhft.lang.Maths;
@@ -66,9 +67,8 @@ import static net.openhft.chronicle.map.Objects.builderEquals;
*
* <p>Use static {@link #of(Class, Class)} method to obtain a {@code ChronicleMapBuilder} instance.
*
* <p>{@code ChronicleMapBuilder} 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 ChronicleMapBuilder} is mutable, see a note in {@link ChronicleHashBuilder} interface
* documentation.
*
* <p>Later in this documentation, "ChronicleMap" means "ChronicleMaps, created by {@code
* ChronicleMapBuilder}", unless specified different, because theoretically someone might provide {@code
@@ -85,6 +85,8 @@ import static net.openhft.chronicle.map.Objects.builderEquals;
*
* @param <K> key type of the maps, produced by this builder
* @param <V> value type of the maps, produced by this builder
* @see ChronicleMap
* @see ChronicleSetBuilder
*/
public class ChronicleMapBuilder<K, V> implements Cloneable,
ChronicleHashBuilder<K, ChronicleMap<K, V>, ChronicleMapBuilder<K, V>> {
@@ -586,6 +588,13 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
return this;
}
@Override
public ChronicleMapBuilder<K, V> disableReplication() {
identifier = -1;
replicators.clear();
return this;
}
@Override
public ChronicleMapBuilder<K, V> timeProvider(TimeProvider timeProvider) {
this.timeProvider = timeProvider;
@@ -615,6 +624,22 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
objectSerializer;
}
/**
* {@inheritDoc}
*
* <p>Example: <pre>{@code Map<Key, Value> map =
* ChronicleMapBuilder.of(Key.class, Value.class)
* .entries(1_000_000)
* .keySize(50).valueSize(200)
* // this class hasn't implemented yet, just for example
* .objectSerializer(new KryoObjectSerializer())
* .create();}</pre>
*
* <p>This serializer is used to serialize both keys and values, if they both require this:
* loosely typed, nullable, and custom {@linkplain #keyMarshaller(BytesMarshaller) key}
* and {@linkplain #valueMarshallerAndFactory(BytesMarshaller, ObjectFactory) value} marshallers
* are not configured.
*/
@Override
public ChronicleMapBuilder<K, V> objectSerializer(ObjectSerializer objectSerializer) {
this.objectSerializer = objectSerializer;
@@ -622,6 +647,11 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
}
/**
* {@inheritDoc}
*
* <p>Example:
*/
@Override
public ChronicleMapBuilder<K, V> keyMarshaller(@NotNull BytesMarshaller<K> keyMarshaller) {
keyBuilder.marshaller(keyMarshaller, null);
src/main/java/net/openhft/chronicle/map/MapEventListener.java
+39 -13
View File
@@ -21,10 +21,29 @@ import net.openhft.lang.io.Bytes;
import java.io.Serializable;
/**
* This event listener is called when key events occur.
* <p>All these calls are synchronous while a lock is held so make them as quick as possible</p>
* <p/>
* TODO specify more clearly in which cases methods are called.
* Contains methods which are called when {@link ChronicleMap} key events occur. Typical use cases:
* <ul>
* <li>Map data backup / replication.</li>
* <li>Logging, monitoring, debugging.</li>
* </ul>
*
* <p>This is an adapter class - all methods have default implementations as no-ops. Extend this
* class and override only methods corresponding the events you are interested in.
*
* <p>To configure {@code MapEventListener} for {@code ChronicleMap}, use
* {@link ChronicleMapBuilder#eventListener(MapEventListener)} method.
*
* <p>{@link MapEventListeners} uninstantiable class contains several logging implementations and
* the default {@linkplain MapEventListeners#nop() no-op implementation}.
*
* <p>All these calls are synchronous while a {@code ChronicleMap} lock is held so make them
* as quick as possible.
*
* @param <K> key type of the maps, trackable by this event listener
* @param <V> value type of the maps, trackable by this event listener
* @param <M> {@code ChronicleMap} subtype, trackable by this event listener
* @see ChronicleMapBuilder#eventListener(MapEventListener)
* @see MapEventListeners
*/
public abstract class MapEventListener<K, V, M extends ChronicleMap<K, V>>
implements Serializable {
@@ -51,14 +70,23 @@ public abstract class MapEventListener<K, V, M extends ChronicleMap<K, V>>
}
/**
* This method is called if a key/value is put in the map.
* This method is call whenever a new value is put for the key in the map during calls of such
* methods as {@link ChronicleMap#put put}, {@link ChronicleMap#putIfAbsent putIfAbsent},
* {@link ChronicleMap#replace(Object, Object, Object) replace}, etc. When a new value is
* {@linkplain ChronicleMapBuilder#defaultValue(Object) default} for the map or obtained during
* {@link ChronicleMap#acquireUsing acquireUsing} call is put for the key, this method is called
* as well.
*
* @param map accessed
* @param entry added/modified
* @param metaDataBytes length of the meta data
* @param added if this is a new entry
* @param key looked up
* @param value set for key
* <p>This method is called when put is already happened.
*
* @param map the accessed map
* @param entry bytes of the entry (with the value already written to)
* @param metaDataBytes length of meta data for this map
* @param added {@code true} is the key was absent in the map before current
* {@code ChronicleMap} method call, led to putting a value and inherently
* calling this listener method
* @param key the key the value is put for
* @param value the value which was associated with the key
*/
public void onPut(M map, Bytes entry, int metaDataBytes, boolean added, K key, V value) {
// do nothing
@@ -85,6 +113,4 @@ public abstract class MapEventListener<K, V, M extends ChronicleMap<K, V>>
void onRelocation(int pos, SharedSegment segment) {
// do nothing
}
}
src/main/java/net/openhft/chronicle/map/VanillaChronicleMap.java
+4 -2
View File
@@ -969,8 +969,10 @@ class VanillaChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
}
/**
* Removes a key (or key-value pair) from the Segment. <p/> The entry will only be removed if {@code
* expectedValue} equals to {@code null} or the value previously corresponding to the specified key.
* Removes a key (or key-value pair) from the Segment.
*
* <p>The entry will only be removed if {@code expectedValue} equals to {@code null}
* or the value previously corresponding to the specified key.
*
* @param hash2 a hash code related to the {@code keyBytes}
* @return the value of the entry that was removed if the entry corresponding to the {@code keyBytes}
src/main/java/net/openhft/chronicle/set/ChronicleSetBuilder.java
+27 -1
View File
@@ -30,7 +30,17 @@ import java.io.File;
import java.io.IOException;
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.
*
* <p>{@code ChronicleMapBuilder} is mutable, see a note in {@link ChronicleHashBuilder} interface
* documentation.
*
* @param <E> element type of the sets, created by this builder
* @see ChronicleSet
* @see ChronicleMapBuilder
*/
public class ChronicleSetBuilder<E>
implements ChronicleHashBuilder<E, ChronicleSet<E>, ChronicleSetBuilder<E>> {
@@ -175,6 +185,12 @@ public class ChronicleSetBuilder<E>
return this;
}
@Override
public ChronicleSetBuilder<E> disableReplication() {
chronicleMapBuilder.disableReplication();
return this;
}
@Override
public String toString() {
@@ -209,6 +225,16 @@ public class ChronicleSetBuilder<E>
return this;
}
/**
* {@inheritDoc}
*
* <p> Example: <pre>{@code Set<Key> set = ChronicleSetBuilder.of(Key.class)
* .entries(1_000_000)
* .keySize(100)
* // this class hasn't implemented yet, just for example
* .objectSerializer(new KryoObjectSerializer())
* .create();}</pre>
*/
@Override
public ChronicleSetBuilder<E> objectSerializer(ObjectSerializer objectSerializer) {
chronicleMapBuilder.objectSerializer(objectSerializer);