FastHash 0.1.0 [ALPHA-2026-09] — Ultra-Fast Native Hash Engine for Java

---

⚡ Ultra-fast hashing and fingerprinting for the FastJava ecosystem.

FastHash is a deterministic hashing engine for file indexing, deduplication, cache keys and embedding buckets. It provides a stable Java 17 API today while reserving a native xxHash3 and SIMD backend for high-throughput Windows workloads.

Run the File Fingerprint Demo | Run the Hash Benchmark

---

Quick Start

import fastHash.FastHash;

public class Example {
	public static void main(String[] args) {
		byte[] document = "FastJava document".getBytes(java.nio.charset.StandardCharsets.UTF_8);
		long fingerprint = FastHash.hash64(document);
		System.out.printf("Fingerprint: %016x%n", fingerprint);
	}
}

Table of Contents

• Why FastHash?
• Quick Start
• Features
• Real-World Scenarios
• Performance Benchmarks
• API Quick Reference
• Technical Examples & Hero Demos
• Installation
• Documentation
• Platform Support
• License
• Related Projects

---

Why FastHash?

Standard Java hashing often becomes a hidden cost in file indexes, deduplication passes and vector caches:

• Repeated allocation: Converting file or network data into temporary objects increases GC pressure.
• Unstable hot paths: Different callers use different hash contracts, making cache and index behavior inconsistent.
• Throughput ceilings: Scalar byte-at-a-time implementations leave SIMD hardware unused.

FastHash addresses this with a compact, deterministic API:

• Stable fingerprints: The same bytes produce the same 64-bit result across supported Java platforms.
• Range and buffer support: Hash file chunks, direct buffers and network payloads without copying them first.
• Native-ready design: xxHash3, MurmurHash3 and AVX2/AVX-512 backends can replace the fallback without changing callers.

---

Features

• ⚡ Deterministic 64-bit hashing: One contract for indexing, caching and deduplication.
• 📦 Zero temporary objects: Operates directly on arrays and duplicated ByteBuffer views.
• 🔢 Range hashing: Fingerprint file blocks or protocol frames without slicing data.
• 🧩 Native-ready backend: Designed for xxHash3, MurmurHash3 and AVX2/AVX-512 integration.

---

Real-World Scenarios

• File deduplication: Fingerprint large files before content comparison.
• Content indexing: Build fast keys for FastFileIndex and FastFileContentIndex.
• Embedding caches: Bucket vector data in FastAIVectorDB.
• Network caches: Create compact keys for FastNet payload caches.

---

Performance Benchmarks

FastHash is profiled through the included benchmark to make hashing cost visible before native acceleration is enabled.

Metric / Hashing Type	Current Java Fallback	Native Target
Document fingerprint	Deterministic 64-bit hash	xxHash3 SIMD
1 MiB block hash	Measured by benchmark	> 10 GB/s
Range hashing	No input copy	AVX2/AVX-512

The benchmark measures the portable fallback on the local machine. Native throughput is reported only after the SIMD backend is integrated.

---

Measured Benchmark Run

The local benchmark executes 1,000,000 hash operations over the same payload and prints the resulting operations per second:

run-benchmark.bat -> fasthash.HashBenchmark

The verified run completed at 26,391,212 operations per second on the local machine; the result is workload- and machine-dependent, so use the launcher before comparing native SIMD changes.

---

API Quick Reference

Method	Description
hash64(byte[])	Hashes a complete byte array.
hash64(byte[], offset, length)	Hashes a validated range without allocation.
hash64(ByteBuffer)	Hashes remaining bytes without changing buffer position.

---

Technical Examples & Hero Demos

Case	Java Example	Launcher	Description
File and Document Fingerprint	FileFingerprintDemo.java	run-demo.bat	Generates a stable content key for indexing, deduplication or cache records.
Hash Throughput	HashBenchmark.java	run-benchmark.bat	Measures repeated content hashing on the portable backend.

---

Installation

Option 1: Maven (Recommended)

<repositories>
	<repository>
		<id>jitpack.io</id>
		<url>https://jitpack.io</url>
	</repository>
</repositories>
<dependencies>
	<dependency>
		<groupId>com.github.andrestubbe</groupId>
		<artifactId>FastHash</artifactId>
		<version>0.1.0</version>
	</dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
	maven { url 'https://jitpack.io' }
}

dependencies {
	implementation 'com.github.andrestubbe:FastHash:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest FastHash JAR from the GitHub releases page.

---

Documentation

• COMPILE.md: Full compilation guide and launcher instructions.
• REFERENCE.md: Hash API and compatibility contract.
• PHILOSOPHY.md: Allocation and backend principles.
• ROADMAP.md: Planned SIMD milestones.
• CHANGELOG.md: Version history.

---

Platform Support

Platform	Status
Platform	Status
----------	--------
Windows 10/11 x64	Native SIMD planned
Linux	Java fallback
macOS	Java fallback

---

License

MIT License — See LICENSE for details.

---

Related Projects

• FastFileIndex — High-speed file indexing
• FastFileContentIndex — Content comparison and deduplication
• FastAIVectorDB — Embedding storage and bucket caching

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋