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.

The "construct" pair is the strongest signal that allocation, not branching, dominates the gap. constructNothing returns the cached singleton, whereas constructJust allocates a fresh wrapper. On hot paths producing many Just or Right values, that allocation cost is real.

VTask

Virtual thread overhead is the dominant cost for simple operations. For real workloads involving I/O, this overhead is negligible, and the scheduling story flips dramatically in VTask's favour.

The blocking I/O numbers come from VTaskVsPlatformThreadsBenchmark. Platform throughput collapses as concurrency grows because OS threads become the bottleneck; virtual thread throughput stays roughly flat because the scheduler parks blocked carriers freely. This is the strongest single argument for VTask in I/O-bound workloads.

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

PCollections via ListKind

PCollectionsHktBenchmark measures PVector against ArrayList when both are processed through the standard ListMonad/ListTraverse pipeline. The widen/narrow boundary itself is free; the cost lives in iteration.

The traverse case is the headline result. The more applicative work an operation does per element, the smaller the gap, because applicative map2 and Kind boxing dominate the underlying iteration cost. See PCollections Integration for the full table and methodology.

Free Monad

Free trades raw speed for program-as-data: a Free programme can be inspected, transformed, or interpreted multiple ways before it is run. That flexibility costs at least three orders of magnitude versus direct function composition.

If a workload is on a hot path and does not benefit from inspection or alternative interpreters, prefer direct composition. Free shines when the same programme is interpreted multiple ways, when the structure is analysed before execution, or when the alternatives would require substantial duplication.

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 three 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.
3. Reflexive parallelism on trivial work. VTaskParBenchmark shows par* variants running thousands of times slower than their sequential equivalents when the per-task work is negligible. Forking, joining, and synchronising all cost more than a few-nanosecond computation. Reach for Par.zip, Par.map2, or Scope only when each branch does enough work to amortise the structured-concurrency cost.

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

Previous: Release History