Zero-allocation hashing for Java
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Add metrohash implementation (#26) Aug 6, 2018
.travis.yml Add JDK10 and remove JDK6 from Travis testing Jul 26, 2018
README.adoc Add metrohash implementation (#26) Aug 6, 2018
pom.xml [maven-release-plugin] prepare for next development iteration Feb 27, 2017

README.adoc

Zero-Allocation Hashing

Version

badge

Overview

This project provides a Java API for hashing any sequences of bytes in Java, including all kinds of primitive arrays, buffers, `CharSequence`s and more.

Written for Java 6+ under Apache 2.0 license.

The key difference compared to other similar projects, e.g. Guava hashing, is that this has no object allocations during the hash computation and does not use ThreadLocal.

The implementation utilises native access where possible, but is also platform-endianness-agnostic. This provides consistent results whatever the byte order, while only moderately affecting performance.

Currently long-valued hash function interface is defined, with the following implementations:

  • xxHash.

  • Two algorithms from FarmHash: farmhashna (introduced in FarmHash 1.0) and farmhashuo (introduced in FarmHash 1.1).

  • CityHash, version 1.1 (latest; 1.1.1 is a C++ language-specific maintenance release).

  • MurmurHash3.

  • MetroHash (using the metrohash64_2 initialization vector).

These are thoroughly tested with JDK 6, 7 and 8, on little-endian platform. However they are believed to be independent from the native byte order.

Performance

Tested on Intel Core i7-4870HQ CPU @ 2.50GHz

Algorithm Speed, GB/s Bootstrap, ns

xxHash

9.5

6

FarmHash na

9.0

6

FarmHash uo

7.2

7

CityHash

7.0

7

MurmurHash

5.3

12

To sum up,

When to use Zero-Allocation Hashing

  • You need to hash plain byte sequences, memory blocks or "flat" objects.

  • You want zero-allocation and good performance (at Java scale).

  • You need hashing to be agile with regards to byte ordering.

When not to use Zero-Allocation Hashing

  • You need to hash POJOs whose actual data is scattered in memory between managed objects. There is no simple way to hash these using this project, for example, classes such as:

        class Person {
            String givenName, surName;
            int salary;
        }
  • You need to hash byte sequences of unknown length, for the simpliest example, Iterator<Byte>.

  • You need to transform the byte sequence (e.g. encode or decode it with a specific coding), and hash the resulting byte sequence on the way without dumping it to memory.

Quick start

Gradle:

dependencies {
    compile 'net.openhft:zero-allocation-hashing:0.8'
}

Or Maven:

<dependency>
  <groupId>net.openhft</groupId>
  <artifactId>zero-allocation-hashing</artifactId>
  <version>0.8</version>
</dependency>

In Java:

long hash = LongHashFunction.xx().hashChars("hello");

See JavaDocs for more information.

Contributions are most welcome!

See the list of open issues.