8477: Add opt-in memory-mapped file support for event storage

[jbachorik]

!WARNING!
This PR depends on #690 - it will stay in draft until the other PR is merged.

Summary

Implements JMC-8477: Add opt-in memory-mapped file support to JFR Writer API for off-heap event storage.

Problem

The current JFR Writer API stores all event data in on-heap byte arrays during recording creation, causing:

• Heap pressure from large byte array allocations
• GC overhead from frequent allocation/deallocation
• Unbounded memory growth with recording size
• Scalability issues for long-running or high-throughput scenarios

Solution

This PR adds opt-in memory-mapped file support, allowing event data to be stored off-heap.

API

Users opt in via the builder pattern:

Recording recording = Recordings.newRecording(outputStream,
    settings -> settings.withMmap(4 * 1024 * 1024)  // 4MB per thread
                        .withJdkTypeInitialization());

Benefits

• Reduced Heap Pressure: Event data stored off-heap eliminates large on-heap allocations
• Predictable Memory Usage: Fixed memory footprint per thread regardless of recording size
• Improved Performance: JMH benchmarks show 8-12% throughput improvement
• Better Scalability: Multiple recordings can coexist without competing for heap space
• Fully Backward Compatible: Heap mode remains the default; opt-in only

Performance Results

JMH benchmarks show consistent improvements across event types:

• writeSimpleEvent: +8.3% (909K → 985K ops/s)
• writeMultiFieldEvent: +11.9% (787K → 881K ops/s)
• writeRepeatedStringsEvent: +11.9% (793K → 887K ops/s)
• writeStringHeavyEvent: +10.4% (801K → 884K ops/s)

Backward Compatibility

• ✅ Heap mode remains the default behavior
• ✅ Existing API unchanged - no breaking changes
• ✅ All existing tests pass without modification
• ✅ New functionality accessed only through explicit opt-in

Testing

• Unit Tests: 850+ lines covering core functionality
• Integration Tests: Multi-threaded stress tests, large event tests
• Benchmarks: Comprehensive JMH benchmark suite with comparison tools
• Validation: All existing JFR Writer tests pass

Commits

1. Add JMH benchmark infrastructure (44aa637) - JMH benchmarks for performance validation
2. Add memory-mapped file support (5def325) - Core mmap implementation
3. Refactor to builder pattern (aaddf98) - Move from system properties to builder API
4. Fix JMH benchmark build (7264aa4) - Enable out-of-the-box benchmark execution
5. Add comparison tool (449eefd) - Python script for benchmark result analysis

Documentation

• README.md with comprehensive usage instructions
• JMH benchmark guide with examples
• Comparison tool for performance analysis

🤖 Generated with Claude Code

---

Progress

• Commit message must refer to an issue
• Change must be properly reviewed (1 review required, with at least 1 Committer)

Integration blocker

 ⚠️ Title mismatch between PR and JBS for issue JMC-8477

Issue

• JMC-8477: JFR Writer: Add opt-in memory-mapped file support for event storage (Enhancement - P4) ⚠️ Title mismatch between PR and JBS.

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jmc.git pull/691/head:pull/691
$ git checkout pull/691

Update a local copy of the PR:
$ git checkout pull/691
$ git pull https://git.openjdk.org/jmc.git pull/691/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 691

View PR using the GUI difftool:
$ git pr show -t 691

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jmc/pull/691.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back jbachorik! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[mlbridge]

Webrevs

• 00: Full (449eefdc)