net.openhft.chronicle.hash

Interface ChronicleHash<K,E extends HashEntry<K>,SC extends HashSegmentContext<K,?>,EQC extends ExternalHashQueryContext<K>>

All Superinterfaces:

AutoCloseable, Closeable, net.openhft.chronicle.core.io.ManagedCloseable, MapClosable, net.openhft.chronicle.core.io.QueryCloseable

All Known Subinterfaces:

ChronicleMap<K,V>, ChronicleSet<K>

public interface ChronicleHash<K,E extends HashEntry<K>,SC extends HashSegmentContext<K,?>,EQC extends ExternalHashQueryContext<K>>
extends MapClosable

Common base interface for ChronicleMap and ChronicleSet.

Method Summary

Modifier and Type	Method and Description
void	close() Releases the off-heap memory, used by this hash container and resources, used by replication, if any.
File	file() Returns the file this hash container mapped to, i.
void	forEachEntry(Consumer<? super E> action) Performs the given action for each entry in this ChronicleHash until all entries have been processed or the action throws an Exception.
boolean	forEachEntryWhile(Predicate<? super E> predicate) Checks the given predicate on each entry in this ChronicleHash until all entries have been processed or the predicate returns false for some entry, or throws an Exception.
default boolean	isOpen() Tells whether or not this ChronicleHash (on-heap instance) is open.
Class<K>	keyClass()
Type	keyType()
long	longSize() Returns the number of entries in this store.
String	name() Returns the name of this ChronicleHash, configured by ChronicleHashBuilder.name(String), or null, if not configured.
long	offHeapMemoryUsed() Returns the amount of off-heap memory (in bytes), allocated by this ChronicleHash or shared with with other ChronicleHashes, persisting to the same file().
EQC	queryContext(net.openhft.chronicle.bytes.BytesStore<?,?> keyBytes, long offset, long size) Returns a context to perform arbitrary operations with the given key, provided in the serialized form.
EQC	queryContext(Data<K> key) Returns a context to perform arbitrary operations with the given key, provided in Data form.
EQC	queryContext(K key) Returns a context to perform arbitrary operations with the given key in this store.
SC	segmentContext(int segmentIndex) Returns a context of the segment with the given index.
int	segments() Returns the number of segments in this ChronicleHash.
String	toIdentityString() Returns a String, useful for identifying this ChronicleHash in debugging, logging, and error reporting.

Methods inherited from interface net.openhft.chronicle.map.MapClosable

isClosed

Methods inherited from interface net.openhft.chronicle.core.io.ManagedCloseable

createdHere, throwExceptionIfClosed, warnAndCloseIfNotClosed

Methods inherited from interface net.openhft.chronicle.core.io.Closeable

closeQuietly, closeQuietly

Methods inherited from interface net.openhft.chronicle.core.io.QueryCloseable

isClosing

Method Detail

file

@Nullable
File file()

Returns the file this hash container mapped to, i. e. when it is created by ChronicleHashBuilder.create() call, or null if it is purely in-memory, i. e. if it is created by ChronicleHashBuilder.create() call.

Returns:

the file this ChronicleMap or ChronicleSet is mapped to, or null if it is not mapped to any file

See Also:

ChronicleHashBuilder.createPersistedTo(File)

name

@Nullable
String name()

Returns the name of this ChronicleHash, configured by ChronicleHashBuilder.name(String), or null, if not configured.

Returns:

the name of this this ChronicleMap or ChronicleSet

toIdentityString

@NotNull
String toIdentityString()

Returns a String, useful for identifying this ChronicleHash in debugging, logging, and error reporting. Object.toString() of concrete ChronicleHash subinterfaces, ChronicleMap and ChronicleSet, has to follow Map.toString() and Set.toString() contracts respectively, making it not always useful (or even impossible to use, if this ChronicleHash contains a lot of entries) for the purposes listed above.

This method return a string of the form:

[ChronicleMap|ChronicleSet]{name=name(), file=file(), identityHashCode=System.identityHashCode(thisChronicleHash)}

This form could be changed in any subsequent Chronicle Map library release (including patch release). The user code shouldn't depend on this form.

Returns:

a String, useful for identifying this ChronicleHash in debugging, logging, and error reporting

longSize

long longSize()

Returns the number of entries in this store.

Returns:

the number of entries in this store

offHeapMemoryUsed

long offHeapMemoryUsed()

Returns the amount of off-heap memory (in bytes), allocated by this ChronicleHash or shared with with other ChronicleHashes, persisting to the same file().

After close() this method returns 0.

Returns:

the amount of off-heap memory, used by this ChronicleHash (in bytes)

keyClass

Class<K> keyClass()

Returns:

the class of <K>

keyType

Type keyType()

Returns:

Type as a Class or UnresolvedType if unknown.

queryContext

@NotNull
EQC queryContext(K key)

Returns a context to perform arbitrary operations with the given key in this store. Conventionally, should be used in a try-with-resources block:

 try (ExternalHashQueryContext<K> q = hash.queryContext(key)) {
     // ... do something
 }

See documentation to HashQueryContext interface and methods in MapMethods interface for examples of using contexts. Also see Working with an entry within a context section in the Chronicle Map tutorial.

Parameters:

key - the queried key

Returns:

the context to perform operations with the key

See Also:

HashQueryContext, MapQueryContext, ExternalHashQueryContext, MapMethods

queryContext

@NotNull
EQC queryContext(Data<K> key)

Returns a context to perform arbitrary operations with the given key, provided in Data form. Equivalent to queryContext(Object), but accepts Data instead of object key. This method is useful, when you already have Data, calling this method instead of queryContext(Object) might help to avoid unnecessary deserialization.

See documentation to HashQueryContext interface and methods in MapMethods interface for examples of using contexts. Also see Working with an entry within a context section in the Chronicle Map tutorial.

Parameters:

key - the queried key as Data

Returns:

the context to perform operations with the key

queryContext

@NotNull
EQC queryContext(net.openhft.chronicle.bytes.BytesStore<?,?> keyBytes,
                          long offset,
                          long size)

Returns a context to perform arbitrary operations with the given key, provided in the serialized form. See queryContext(Object) and queryContext(Data) for more information on contexts semantics and usage patterns.

Parameters:

keyBytes - the bytes store with the key bytes to query

offset - actual offset of the key bytes within the given BytesStore

size - length of the key bytes sequence within the given BytesStore

Returns:

the context to perform operations with the key

segmentContext

SC segmentContext(int segmentIndex)

Returns a context of the segment with the given index. Segments are indexed from 0 to segments()- 1.

See Also:

HashSegmentContext

segments

int segments()

Returns the number of segments in this ChronicleHash.

See Also:

ChronicleHashBuilder.minSegments(int), ChronicleHashBuilder.actualSegments(int)

forEachEntryWhile

boolean forEachEntryWhile(Predicate<? super E> predicate)

Checks the given predicate on each entry in this ChronicleHash until all entries have been processed or the predicate returns false for some entry, or throws an Exception. Exceptions thrown by the predicate are relayed to the caller.

The order in which the entries will be processed is unspecified. It might differ from the order of iteration via Iterator returned by any method of this ChronicleHash or it's collection view.

If the ChronicleHash is empty, this method returns true immediately.

Parameters:

predicate - the predicate to be checked for each entry

Returns:

true if the predicate returned true for all entries of the ChronicleHash, false if it returned false for the entry

forEachEntry

void forEachEntry(Consumer<? super E> action)

Performs the given action for each entry in this ChronicleHash until all entries have been processed or the action throws an Exception. Exceptions thrown by the action are relayed to the caller.

The order in which the entries will be processed is unspecified. It might differ from the order of iteration via Iterator returned by any method of this ChronicleHash or it's collection view.

Parameters:

action - the action to be performed for each entry

close

void close()

Releases the off-heap memory, used by this hash container and resources, used by replication, if any. However, if hash container (hence off-heap memory, used by it) is mapped to the file and there are other instances mapping the same data on the server across JVMs, the memory won't be actually freed on operating system level. I. e. this method call doesn't affect other ChronicleMap or ChronicleSet instances mapping the same data.

If you won't call this method, memory would be held at least until next garbage collection. This could be a problem if, for example, you target rare garbage collections, but load and drop ChronicleHashes regularly.

After this method call, all methods, querying the ChronicleHash's entries, longSize() and size()), throw ChronicleHashClosedException. isOpen() returns false, close() itself returns immediately without effects (i. e. repetitive close(), even from concurrent threads, are safe).

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

isOpen

default boolean isOpen()

Tells whether or not this ChronicleHash (on-heap instance) is open.

Returns:

true is close() is not yet called