org.neo4j.hashing

Interface HashFunction

public interface HashFunction

A hash function, as per this interface, will produce a deterministic value based on its input.

Hash functions are first initialised with a seed, which may be zero, and then updated with a succession of values that are mixed into the hash state in sequence.

Hash functions may have internal state, but can also be stateless, if their complete state can be represented by the 64-bit intermediate hash state.

See Also:

incrementalXXH64(), javaUtilHashing(), xorShift32()

Method Summary

Modifier and Type	Method and Description
long	finalise(long intermediateHash) Produce a final hash value from the given intermediate hash state.
default long	hashSingleValue(long value) Produce a 64-bit hash value from a single long value.
default int	hashSingleValueToInt(long value) Produce a 32-bit hash value from a single long value.
static HashFunction	incrementalXXH64() Our incremental XXH64 based hash function.
long	initialise(long seed) Initialise the hash function with the given seed.
static HashFunction	javaUtilHashing() Same hash function as that used by the standard library hash collections.
default int	toInt(long hash) Reduce the given 64-bit hash value to a 32-bit value.
long	update(long intermediateHash, long value) Update the hash state by mixing the given value into the given intermediate hash state.
static HashFunction	xorShift32() The default hash function is based on a pseudo-random number generator, which uses the input value as a seed to the generator.

Method Detail

initialise

long initialise(long seed)

Initialise the hash function with the given seed.

Different seeds should produce different final hash values.

Parameters:

seed - The initialisation seed for the hash function.

Returns:

An initialised intermediate hash state.

update

long update(long intermediateHash,
            long value)

Update the hash state by mixing the given value into the given intermediate hash state.

Parameters:

intermediateHash - The intermediate hash state given either by initialise(long), or by a previous call to this function.

value - The value to add to the hash state.

Returns:

a new intermediate hash state with the value mixed in.

finalise

long finalise(long intermediateHash)

Produce a final hash value from the given intermediate hash state.

Parameters:

intermediateHash - the intermediate hash state from which to produce a final hash value.

Returns:

the final hash value.

toInt

default int toInt(long hash)

Reduce the given 64-bit hash value to a 32-bit value.

Parameters:

hash - The hash value to reduce.

Returns:

The 32-bit representation of the given hash value.

hashSingleValue

default long hashSingleValue(long value)

Produce a 64-bit hash value from a single long value.

Parameters:

value - The single value to hash.

Returns:

The hash of the given value.

hashSingleValueToInt

default int hashSingleValueToInt(long value)

Produce a 32-bit hash value from a single long value.

Parameters:

value - The single value to hash.

Returns:

The hash of the given value.

incrementalXXH64

static HashFunction incrementalXXH64()

Our incremental XXH64 based hash function.

This hash function is based on xxHash (XXH64 variant), but modified to work incrementally on 8-byte blocks instead of on 32-byte blocks. Basically, the 32-byte block hash loop has been removed, so we use the 8-byte block tail-loop for the entire input.

This hash function is roughly twice as fast as the hash function used for index entries since 2.2.0, about 30% faster than optimised murmurhash3 implementations though not as fast as optimised xxHash implementations due to the smaller block size. It is allocation free, unlike its predecessor. And it retains most of the excellent statistical properties of xxHash, failing only the "TwoBytes" and "Zeroes" keyset tests in SMHasher, passing 12 out of 14 tests. According to Yann Collet on twitter, this modification is expected to mostly cause degraded performance, and worsens some of the avalanche statistics.

This hash function is stateless, so the returned instance can be freely cached and accessed concurrently by multiple threads.

The xxHash algorithm is originally by Yann Collet, and this implementation is with inspiration from Vsevolod Tolstopyatovs implementation in the Zero Allocation Hashing library. Credit for SMHasher goes to Austin Appleby.

javaUtilHashing

static HashFunction javaUtilHashing()

Same hash function as that used by the standard library hash collections. It generates a hash by splitting the input value into segments, and then re-distributing those segments, so the end result is effectively a striped and then jumbled version of the input data. For randomly distributed keys, this has a good chance at generating an even hash distribution over the full hash space.

It performs exceptionally poorly for sequences of numbers, as the sequence increments all end up in the same stripe, generating hash values that will end up in the same buckets in collections.

This hash function is stateless, so the returned instance can be freely cached and accessed concurrently by multiple threads.

xorShift32

static HashFunction xorShift32()

The default hash function is based on a pseudo-random number generator, which uses the input value as a seed to the generator. This is very fast, and performs well for most input data. However, it is not guaranteed to generate a superb distribution, only a "decent" one.

This hash function is stateless, so the returned instance can be freely cached and accessed concurrently by multiple threads.