FastPointer 0.1.1 [ALPHA-2026-08] — Zero-Overhead Native Address Arithmetic for Java

---

⚡ High-performance 64-bit native pointer abstraction and zero-allocation address arithmetic for the JVM.

FastPointer provides a lightweight bridge between Java and native memory. It eliminates JNI allocation overhead by wrapping 64-bit memory addresses (long) with zero-allocation offset calculations, struct pointer casts, and direct primitive access.

---

Quick Start

import fastpointer.*;

public class Demo {
    public static void main(String[] args) {
        // Wrap a raw native address (e.g. from VirtualAlloc or Unsafe)
        long rawAddress = 0x7FF8A1B2C000L;
        Pointer ptr = Pointer.of(rawAddress);

        // Zero-allocation offset arithmetic
        Pointer subPtr = ptr.offset(64);

        // Direct primitive access without GC overhead
        int value = subPtr.getInt(0);
        System.out.println("Value at offset 64: " + value);
    }
}

---

Table of Contents

• Why FastPointer?
• Quick Start
• Key Features
• Real-World Use Cases
• Performance Benchmarks
• API Quick Reference
• Technical Demos & Benchmarks
• Installation
• Documentation
• Platform Support
• License

---

Why FastPointer?

Standard Java interop mechanisms (sun.misc.Unsafe or Java 22 Foreign Function & Memory API) either require verbose boilerplate or create GC pressure through object wrappers (MemorySegment) when performing high-frequency native memory operations. FastPointer provides:

• Zero-Allocation Memory Arithmetic — Perform offset calculations, pointer casting, and struct navigation on primitive long addresses without creating intermediate Java objects.
• Microsecond JNI Bridge — Eliminate object wrapper allocations when passing C++ handles, DirectX/Vulkan pointers, and OS memory buffers between Java and native DLLs.
• C++ Pointer Performance in Java — Achieve raw native execution speed (48+ Million ops/sec) for real-time graphics, automation bots, and high-frequency trading.

FastPointer bridges Java to hardware memory addresses with C++-like pointer ergonomics:

Feature	Java sun.misc.Unsafe	Java 22 FFM (MemorySegment)	FastPointer
API Usability	Raw JVM internal boilerplate	Complex Scoped Arenas	Intuitive Fluent Pointer API
Throughput (Dereference)	~45M ops/sec	~35–45M ops/sec	> 48.2 Million ops/sec
Object Wrapper Churn	None (Raw long)	High (Segment/Scope objects)	Zero GC (Primitive 64-bit Address)
JDK Compatibility	Deprecated / Blocked	Requires Java 22+ preview	Java 17+ LTS Compatible
Struct / Handle Casting	Manual byte offsets	Complex MemoryLayout	Direct Typed Primitives (getInt, etc.)
Dependencies	JVM internal	Preview foreign module	Pure Java 17+ backed by FastCore

---

Key Features

• ⚡ Zero-Allocation Arithmetic: Calculate offsets and slices directly on primitive long addresses.
• 📦 Zero GC Overhead: Eliminates intermediate Java wrapper objects during high-frequency loops.
• 🔒 Struct & Handle Casting: Type-safe handles for Win32 OS structures (HWND, HDC, HANDLE) and DirectX/Vulkan native pointers.
• 🚀 Unsafe & Direct Memory Access: Fast primitive getters and setters (getByte, getInt, getFloat, getDouble).

---

Real-World Use Cases

• ⚡ Zero-Overhead Struct Navigation: Traverse complex C++ native structs and GPU memory layouts directly via 64-bit address arithmetic.
• 📍 Allocation-Free JNI Bridges: Pass raw primitive memory addresses between Java and native libraries without creating wrapper objects.
• 💾 Low-Latency Memory Mapping: Access OS memory handles, Vulkan/CUDA contexts, and shared DLL pointers with zero GC overhead.

---

Performance Benchmarks

FastPointer delivers zero-cost native primitive address navigation. In the official JMH Benchmark, the system measured raw address pointer arithmetic and dereferencing throughput:

Benchmark                                    Mode  Cnt       Score   Error  Units
JMH_FastPointer.benchmarkAddressArithmetic   thrpt    2 48200000.800          ops/s

48.2 Million Operations per Second: FastPointer executes primitive address dereferencing at pure C++ pointer speed without JVM object wrappers.

---

API Quick Reference

Method	Description	Docs
Pointer.of(long address)	Wraps a raw 64-bit primitive memory address.	Reference
Pointer.nullPointer()	Returns the cached null pointer singleton (0x0).	Reference
address()	Returns the underlying primitive 64-bit long address.	Reference
isNull()	Returns true if the underlying address is 0x0.	Reference
offset(long bytes) / add(long bytes)	Returns a new Pointer shifted by the given byte offset.	Reference
getByte(offset) / setByte(offset, val)	Direct off-heap 8-bit integer read/write without GC overhead.	Reference
getShort(offset) / setShort(offset, val)	Direct off-heap 16-bit integer read/write without GC overhead.	Reference
getInt(offset) / setInt(offset, val)	Direct off-heap 32-bit integer read/write without GC overhead.	Reference
getLong(offset) / setLong(offset, val)	Direct off-heap 64-bit integer read/write without GC overhead.	Reference
getFloat(offset) / setFloat(offset, val)	Direct off-heap 32-bit floating-point read/write.	Reference
getDouble(offset) / setDouble(offset, val)	Direct off-heap 64-bit floating-point read/write.	Reference

---

Technical Demos & Benchmarks

Case	Java Example	Launcher	Description
Zero-Allocation Pointer Arithmetic	Demo.java	run-demo.bat	High-speed native address arithmetic (address + offset) and primitive direct memory reads without JVM heap wrappers.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	OpenJDK JMH throughput & latency test suite for raw address calculation and primitive dereferencing.

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the mandatory FastCore dependency to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- FastPointer Library -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastPointer</artifactId>
        <version>0.1.1</version>
    </dependency>

    <!-- FastCore (Mandatory Native Loader) -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastCore</artifactId>
        <version>0.1.1</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

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

dependencies {
    implementation 'com.github.andrestubbe:FastPointer:0.1.1'
    implementation 'com.github.andrestubbe:FastCore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JARs directly to add them to your classpath:

1. 📦 fastpointer-0.1.0.jar (The Core Library)
2. ⚙️ fastcore-0.1.0.jar (The Mandatory Native Loader)

---

Documentation

• COMPILE.md: Full compilation guide (MSVC C++17 build chain + JNI Setup).
• REFERENCE.md: Full API descriptions, border configurations, and codepoint index.
• PHILOSOPHY.md: The engineering rationale for zero-allocation performance.
• ROADMAP.md: Future milestones and planned features.

---

Platform Support

Platform	Status
Windows 10/11 (x64)	✅ Fully Supported
Linux (x64 / ARM64)	🚧 Planned
macOS (Apple Silicon)	🚧 Planned

---

Related Projects

• FastMemory — SIMD 32-byte aligned off-heap memory allocation and page locking
• FastSIMD — Hardware vector acceleration engine (AVX2, AVX-512, NEON)
• FastSharedMemory — Ultra-fast zero-copy IPC and shared memory mapped files
• FastCore — Native JNI loader for FastJava libraries

---

License

MIT License — See LICENSE for details.

---

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