net.openhft.chronicle.hash

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

All Superinterfaces:

AutoCloseable, Closeable

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 Closeable

This interface defines common ChronicleMap and ChronicleSet, related to off-heap memory management and file-mapping. Not usable by itself.

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.
boolean	isOpen() Tells whether or not this ChronicleHash (on-heap instance) is open.
Class<K>	keyClass()
long	longSize()
EQC	queryContext(BytesStore keyBytes, long offset, long size) Returns the context to perform arbitrary operations with the given key, provided in the serialized form.
EQC	queryContext(Data<K> key) Equivalent to queryContext(Object), but accepts Data instead of key as an object.
EQC	queryContext(K key) Returns the context to perform arbitrary operations with the given key in this map.
SC	segmentContext(int segmentIndex) Returns the context of the segment with the given index.
int	segments() Returns the number of segments in this ChronicleHash.

Method Detail

file

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)

longSize

long longSize()

keyClass

Class<K> keyClass()

Returns:

the class of <K>

queryContext

@NotNull
EQC queryContext(K key)

Returns the context to perform arbitrary operations with the given key in this map. Conventionally, try-with-resources block should wrap the returned context:

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

See HashQueryContext and MapMethods for a lot of inspiration about using this functionality.

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)

Equivalent to queryContext(Object), but accepts Data instead of key as an object. Useful, when you already have Data, calling this method instead of queryContext(Object) might help to avoid unnecessary deserialization.

Parameters:

key - the queried key as Data

Returns:

the context to perform operations with the key

queryContext

@NotNull
EQC queryContext(BytesStore keyBytes,
                          long offset,
                          long size)

Returns the 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

Returns:

the context to perform operations with the key

segmentContext

SC segmentContext(int segmentIndex)

Returns the 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.

TODO what about commit guarantees, when ChronicleMap is used with memory-mapped files, if ChronicleMap/ChronicleSet closed/not?

After this method call behaviour of all methods of ChronicleMap or ChronicleSet is undefined. Any method call on the map might throw any exception, or even JVM crash. Shortly speaking, don't call use map closing.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

isOpen

boolean isOpen()

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

Returns:

true is close() is not yet called