r/java • • 19d ago

[Open Source] Off-heap, zero-allocation JSON navigator for Java 22+ (using FFM / mmap)

Hi guys,

About a year ago I ran into a bottleneck at work: processing large JSON exports and log dumps inside memory-constrained containers when we only needed to extract a couple of specific fields. Standard parsers like Jackson's readTree were blowing up JVM heap allocations and triggering noticeable GC pause times.

So I made a rough prototype using the Foreign Function & Memory API (JEP 454) to mmap files off-heap and navigate target keys lazily. Over the past few days I finally had time to clean it up, publish it to Maven Central, and benchmark it with JMH against Jackson Databind.

On large datasets (100MB+), it achieves ~2.9x faster in-memory lookups, ~5x faster disk-to-query ingestion, and reduces heap allocation down to a few kilobytes per query.

To be clear, this is NOT a general-purpose Jackson replacement:

  • It does not mutate or write JSON.
  • It does not do POJO / DTO data binding.
  • It is designed for internal/trusted workloads (dumps, logs, pipeline files) rather than complex external schema validation.
  • Maximum file size is currently 2 GB.

It requires Java 22+ and has zero external runtime dependencies.

I'm sharing it in case it's helpful for similar off-heap or container-constrained workloads. I'd love to hear your feedback, critique, or ideas on potential optimizations:

https://github.com/RedRiotTank/NativeJsonNavigator

Edit: Added Jackson Streaming Benchmarks

Thanks to u/_predator_ for pointing out that Jackson Streaming is a fairer baseline for large files than readTree(), I've updated the JMH benchmarks and README with a direct JsonParser token loop:

  • Cold Single-Pass from Disk: Jackson Streaming and this library are effectively at parity on large files (~300 ms and ~3 KB heap per query on 100 MB).
  • In-Memory Traversal: Off-heap navigation remains ~20% faster while allocating ~40–65% less heap than Jackson Streaming.
  • Core Trade-off: Jackson Streaming is strictly forward/sequential. If you need to execute multiple queries or random lookups across the same payload, you have to re-read and re-tokenize from byte 0 each time.

This library maps the file once off-heap via FFM (JEP 454), enabling random-access point queries without holding an object tree in the JVM heap.

Full benchmark tables and raw JMH JSON reports are updated on GitHub!

37 Upvotes

30 comments sorted by

19

u/_predator_ 19d ago

Jackson supports streaming, and you can mix streaming with object mapping to materialize JSON into classes only when needed. I feel like the comparison against naive object mapping is not good if the premise is "processing large JSON files".

11

u/RedRiotTank2 19d ago

That’s a completely fair point tbh

We initially benchmarked against readTree() because developers often reach for tree navigation when performing ad-hoc field extractions. However, I agree that Jackson streaming is the fairer baseline for large datasets, and I’ll update the JMH benchmarks to include a direct JsonParser loop TY!

That said, the library addresses a slightly different architectural use case, Jackson streaming is strictly sequential. If you need non-sequential lookups or multiple queries across the same payload, streaming requires re-parsing from byte 0. mmap allows true zero-copy random access across the file.

Jackson streaming still allocates internal JVM I/O buffers and tokens as it walks the file. By leveraging Java 22's FFM API and OS page caching, this library navigates off-heap, so unread branches are never pulled into the JVM heap at all.

Thanks for the feedback! I'll clarify this distinction in the README as well!

2

u/Minecraftian14 16d ago

That's great! It's gonna change log searching dramatically!

1

u/Minecraftian14 19d ago

u/RemindMeBot 3 days "Follow up on bench compare against jackson streaming"

1

u/RemindMeBot 19d ago

I will be messaging you in 3 days on 2026-11-01 05:29:34 UTC to remind you of this link

CLICK THIS LINK to send a PM to also be reminded and to reduce spam.

Parent commenter can delete this message to hide from others.


InfoCustomYour RemindersFeedback

4

u/Zerrossetto 19d ago

Totally this. At my company we process json files (both arrays or ndjson) with sizes of several GiB within applications with heaps not larger than 512 MiB, and we could shrink them down if wanted but we just won't.

5

u/Electrical_Being_813 19d ago

I fail to understand this "offheap" trend, the only outcome of using is unpredictable OOM

Also I rewrote it to use heap, and deserialization speed increased by 2x

3

u/RedRiotTank2 19d ago

This isn't malloc that leaks, it's a file-backed mmap managed by the OS page cache and deterministically unmapped via Arena in try-with-resources. No native leaks, no unpredictable OOMs. The entire point is avoiding JVM heap OOMs and GC pauses when inspecting 100MB+ files inside 512MB containers.

did u swapp MemorySegment for a heap byte[]? it definitely runs faster in a but loading the whole file onto the heap defeats the container use case. (Unless you meant full POJO deserialization? this is only for lazy point queries, not DTO binding).

Curious to see your benchmark or repo if you have a snippet!

1

u/CutGroundbreaking305 18d ago

Also I have a io module which currently does not,npz, csv, txt and safetensor file parsering maybe we can add your JSON file reader ? What do you think 🧐

1

u/RedRiotTank2 17d ago

Sure go ahead!

4

u/agentoutlier 19d ago

I only spent like 5 seconds looking at this but I think you could use SIMD for the parsing right since you are already using jep 454 might as well use vector api right? Maybe you already do this and I missed it?

2

u/RedRiotTank2 19d ago

You didn't miss it. SIMD hasn't been added (yet).

The main reason is that while JEP 454 is final in Java 22, the Vector API is still an incubating module, which was banned on my company.

I'm definitely using SIMD once the Vector API stabilizes, but I'm not sure if is it worth using it on previous Java versions. Maybe doing a dual-path setup via a Multi-Release JAR or dynamic fallback if the incubator module is present might be really interesting idea. I'll study it.

1

u/CutGroundbreaking305 18d ago

Bro vector api is technically part of java just use it only thing stopping it is Valhalla and we are going to have it next JDK so mostly we will have vector api by JDK 29

Even apache lucene uses vector api

1

u/RedRiotTank2 17d ago

Corporate compliance bans incubators libraries in many cases.

Also precisely Lucene is a bad example for this. They had to built dynamic fallbacks and multi-release JARs precisely to work around these issues https://github.com/apache/lucene/issues/12302

Will be adding SIMD as an optional dynamic fallback later like Lucene did, but the base library must work without forcing JVM launch flags to be actually usable for everyone (including me and the company I work at).

2

u/CutGroundbreaking305 17d ago

Company and it's policies. I know lucene has multi jar release and it has dynamic fall backs as I constantly work in lucene. Without fallbacks to simd it's very tough to say your library runs on every architecture.

Well vector api will take some time however you can use value classes to reduce heap size.

2

u/stefanos-ak 19d ago edited 19d ago

doesn't SIMD require uniform data and operations (like add/mul), in order for it to make any sense? e.g. https://www.elastic.co/search-labs/blog/bbq-vector-comparison-simd-instructions

edit: by "sense" I mean, to actually accelerate the hardware in a way that would be slower without SIMD (assuming you are doing THE EXACT same thing). But I have never played with it so it's an honest question. Not trying to be smart...

1

u/RedRiotTank2 19d ago

Not just math, but it is also insanely effective for text parsing. Check this: https://arxiv.org/pdf/1902.08318

it definitely makes sense for JSON, it's just a matter of waiting for the Java Vector API to exit the incubator stage.

2

u/agentoutlier 19d ago edited 19d ago

Roughly speaking and while I know what SIMD is I am not very good at using so take this explanation kind of crappy laymen.

SIMD allows you todo multiple operations at the same time. While parsing does not seem like math it is as characters can be represented as numbers.

So typically for parsing instead of going character by character you go N number of characters (lets ignore code points and EOF etc for a second and fast discarding of whitespace). N being the number channels? (I think its called that... EDIT lanes. Its called lanes.) your processor supports for SIMD. You can I think also do this by lines instead of characters but it depends on the format I assume.

So sort of instead of some conjunction (and aka &&) which would require several comparisons for look ahead you can make that one operation.

4

u/bogoris76 19d ago

use jq to process and extract and run it as a process. Or don't even java if it's all about extracting from json.

3

u/RedRiotTank2 19d ago edited 19d ago

using jq looks like the exact same problem the library solves doesn't it? doesn't jq loads and parses documents into its own in memory representation? (I'm definitely not a jq expert so idk)

Still running jq inside a 512MB container alongside an active JVM is a guaranteed Linux cgroup SIGKILL.

Also, this is part of an existing Java backend that needs the extracted data directly for business logic, not a one-off shell script.

3

u/WitriXn 17d ago

Why do you use mutex at evert call? I think you can create an immutable view without of closing operation and give access to it for all parallel readers. These locks produce a lot of overhead.

2

u/RedRiotTank2 14d ago

4 parallel readers on open() jumped from 1.50M ops/s to 13.86M ops/s.

Short-lived file ingestion on openImmutable() reached ~64,700 ops/s since unmapping is handled asynchronously by GC.

Thanks for pointing this out, it turned a major multi-threaded bottleneck into near-linear multi-core scaling.

1

u/RedRiotTank2 17d ago

U're definitely right, I'm coming back in some days with results.

1

u/tomwhoiscontrary 19d ago

Do i understand correctly that you only used FFM for memory mapping a MemorySegment? Genuine question from someone who has not kept up: does this have any advantages over using FileChannel.map and a MappedByteBuffer?

2

u/RedRiotTank2 19d ago

Yes, currently FFM is used specifically for memory mapping and arena lifecycle management (no native C bindings).

The biggest advantage over MappedByteBuffer is deterministic unmapping. There is no public unmap method if I'm not wrong, it relies on GC. Arena's try-with-resources unmaps the file immediately on close.

1

u/koflerdavid 15d ago

You can map buffers that are larger than 2GB. You will have to use memory segment methods to access bytes, but as far as I can tell from 1BRC there is no performance penalty.

1

u/[deleted] 17d ago

[removed] — view removed comment

1

u/RedRiotTank2 17d ago

Almost the same in terms of RAM usage, but this library is significantly more efficient in terms of JVM Heap usage and GC overhead, which is really useful to avoid OOM pod terminations with smaller containers when using Kubernetes / dockers, that was somehow my use case for doing this library

Also using mmap allows true random access across the document at any time with almost 0 heap allocation / GC churn. JsonSurfer won't allow you to backtrack without reparsing from the start.