Benchmarks & Performance

Higher-Kinded-J ships with a comprehensive JMH benchmark suite in the hkj-benchmarks module. These benchmarks measure the real cost of the library's abstractions so you can make informed decisions about where and when to use them.

"Measure. Don't guess." — Kirk Pepperdine, Java performance expert

Why Benchmarks Matter

Functional abstractions wrap values. Wrapping has a cost. The question is never "is there overhead?" — there always is — but "does the overhead matter for my workload?" The benchmark suite answers that question with data rather than intuition.

The suite is designed around three principles:

1. Honesty — measure real abstraction costs, not contrived best cases
2. Comparability — include raw Java baselines alongside library operations
3. Actionability — organise results so regressions are immediately visible

What Is Measured

The hkj-benchmarks module contains 19 benchmark classes covering every major type in the library:

Core Types

Effect Types

Effect Path Wrappers

Comparisons

Running Benchmarks

All Benchmarks

./gradlew :hkj-benchmarks:jmh

A Single Benchmark Class

./gradlew :hkj-benchmarks:jmh --includes=".*VStreamBenchmark.*"
./gradlew :hkj-benchmarks:jmh --includes=".*VTaskBenchmark.*"
./gradlew :hkj-benchmarks:jmh --includes=".*EitherBenchmark.*"

A Single Benchmark Method

./gradlew :hkj-benchmarks:jmh --includes=".*VTaskBenchmark.runSucceed.*"

With GC Profiling

This reveals allocation rates and GC pressure — essential for understanding memory behaviour:

./gradlew :hkj-benchmarks:jmh -Pjmh.profilers=gc

Long / Stress Mode

Runs with chainDepth=10000 and recursionDepth=10000 for thorough stack-safety validation:

./gradlew :hkj-benchmarks:longBenchmark

Formatted Report

./gradlew :hkj-benchmarks:benchmarkReport

Reading the Output

JMH reports throughput in operations per microsecond. Higher is better.

Benchmark                                    Mode  Cnt   Score   Error   Units
EitherBenchmark.rightMap                   thrpt   20  15.234 ± 0.512  ops/us
EitherBenchmark.leftMap                    thrpt   20  89.123 ± 1.234  ops/us

Score is the measured throughput. Error is the 99.9% confidence interval. If the error is larger than ~30% of the score, the result is noisy — increase warmup or measurement iterations.

What to Look For

Warning Signs

Expected Performance by Type

Either and Maybe

These types use instance reuse: Left and Nothing operations return the same object without allocating, making short-circuit paths essentially free.

VTask

Virtual thread overhead is the dominant cost for simple operations. For real workloads involving I/O, this overhead is negligible.

VStream

VStream's pull-based model adds overhead per element compared to Java Stream's push model, but provides laziness, virtual thread execution, and error recovery that Java Stream cannot.

Effect Path Wrappers

Benchmark Assertion Tests

The benchmark suite includes automated assertion tests that validate performance characteristics after each benchmark run. These are not just "did it finish?" checks — they verify relative performance, overhead ratios, and sanity bounds.

What the Tests Validate

Running the Tests

# Step 1: Run benchmarks (generates results.json)
./gradlew :hkj-benchmarks:jmh

# Step 2: Run assertion tests against the results
./gradlew :hkj-benchmarks:test

# Or run both together via the benchmarkValidation task
./gradlew benchmarkValidation

Release Quality Gate

The releaseReadiness task is a single-command quality gate that runs every verification step, ordered from fastest to slowest so failures surface early:

./gradlew releaseReadiness

If any step fails, the build stops immediately. All five must pass before a release.

Reports Generated

After a successful run, reports are available at:

When Overhead Matters (and When It Doesn't)

The benchmarks consistently show that abstraction overhead is measured in nanoseconds. Real-world operations — database queries, HTTP calls, file reads — are measured in milliseconds. The overhead is three to four orders of magnitude smaller than any I/O operation.

Abstraction overhead matters in exactly two scenarios:

1. Tight computational loops processing millions of items per second with no I/O — use primitives directly
2. Very long chains (hundreds of steps) creating GC pressure — break into named submethods

For everything else, the type safety, composability, and testability benefits far outweigh the cost.

Previous: Release History