Project Awesome project awesome
♥

Zero-Allocation-Hashing

Hashing any sequences of bytes in Java, including all kinds of primitive arrays, buffers, CharSequences and more.

Package 843 stars GitHub

= Zero-Allocation Hashing :toc: :pp: ++ :lang: en-GB :source-highlighter: rouge

Chronicle Software

image:https://maven-badges.herokuapp.com/maven-central/net.openhft/zero-allocation-hashing/badge.svg[caption="",link=https://maven-badges.herokuapp.com/maven-central/net.openhft/zero-allocation-hashing] image:https://javadoc.io/badge2/net.openhft/zero-allocation-hashing/javadoc.svg[link="https://www.javadoc.io/doc/net.openhft/zero-allocation-hashing/latest/index.html"] //image:https://javadoc-badge.appspot.com/net.openhft/zero-allocation-hashing.svg?label=javadoc[JavaDoc, link=https://www.javadoc.io/doc/net.openhft/zero-allocation-hashing] image:https://img.shields.io/github/license/OpenHFT/Zero-Allocation-Hashing[GitHub] image:https://img.shields.io/badge/release%20notes-subscribe-brightgreen[link="https://chronicle.software/release-notes/"] image:https://sonarcloud.io/api/project_badges/measure?project=OpenHFT_Zero-Allocation-Hashing&metric=alert_status[link="https://sonarcloud.io/dashboard?id=OpenHFT_Zero-Allocation-Hashing"]

toc::[]

== About

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

Written for Java 8+ under Apache 2.0 licence.

The key difference compared to other similar projects, e.g. https://guava.dev/releases/28.1-jre/api/docs/com/google/common/hash/package-summary.html[Guava hashing], is that this has no object allocation 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 for 64-bit hash, and long[]-valued hash function interface for more than 64-bit hash, with the following implementations (in alphabetical order):

These are thoroughly tested with https://www.oracle.com/java/technologies/java-se-support-roadmap.html[LTS JDKs] 8, 11, 17, and 21, plus the latest non-LTS JDKs on both little- and big-endian platforms. Other non-LTS JDKs from 9 should also work, but they will not be tested from half a year after EOL.

=== 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 |MetroHash |https://github.com/OpenHFT/Zero-Allocation-Hashing/issues/28[??] | https://github.com/OpenHFT/Zero-Allocation-Hashing/issues/28[??] |WyHash |https://github.com/OpenHFT/Zero-Allocation-Hashing/issues/28[??] |https://github.com/OpenHFT/Zero-Allocation-Hashing/issues/28[??]

|===

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:

[source,Java]

class Person {
    String givenName, surName;
    int salary;
}

  • You need to hash byte sequences of unknown length, for the simplest 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.

=== Javadoc

See http://javadoc.io/doc/net.openhft/zero-allocation-hashing/latest

=== Internal documentation

  • link:src/main/docs/specifications.adoc[Requirements overview]
  • link:src/main/docs/architecture-overview.adoc[Architecture overview]
  • link:src/main/docs/invariants-and-contracts.adoc[Invariants and contracts]
  • link:src/main/docs/algorithm-profiles.adoc[Algorithm profiles]
  • link:src/main/docs/testing-strategy.adoc[Testing strategy]
  • link:src/main/docs/performance-benchmarks.adoc[Performance benchmarks]
  • link:src/main/docs/unsafe-and-platform-notes.adoc[Unsafe and platform notes]
  • link:src/main/docs/change-log-template.adoc[Change-log template]

== Quick start

Gradle:

[source,groovy]

dependencies { implementation 'net.openhft:zero-allocation-hashing:0.27ea1'

}

Or Maven:

[source,xml]

net.openhft zero-allocation-hashing 0.27ea1 ----

In Java:

[source,Java]

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

See http://javadoc.io/doc/net.openhft/zero-allocation-hashing/latest[JavaDocs] for more information.

== Contributions are most welcome!

See the list of https://github.com/OpenHFT/Zero-Allocation-Hashing/issues[open issues].

Back to JVM