VStream Performance: Benchmarks and Optimisation

Measuring the Cost of Lazy, Effectful Streaming

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

Why Measure?

VStream wraps every element pull in a VTask, which evaluates on a virtual thread. That wrapping has a cost. The question is never "is there overhead?" but "does the overhead matter for my workload?" The benchmarks in this page answer that question with data.

For simple in-memory transformations, Java Stream is faster. For I/O-bound pipelines with concurrent element processing, VStream with parEvalMap is more capable and often faster end-to-end.

Package: org.higherkindedj.benchmarks Module: hkj-benchmarks

Benchmark Methodology

All benchmarks use JMH (Java Microbenchmark Harness) with the following configuration:

@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.MICROSECONDS)
@State(Scope.Thread)

For GC profiling:

./gradlew :hkj-benchmarks:jmh --includes=".*VStreamBenchmark.*" -PjmhProfilers=gc

Performance Characteristics

Construction Cost

VStream construction is lightweight. All factory methods return lazy descriptions without allocating element storage:

Combinator Overhead

Combinators like map, filter, and flatMap are lazy: they build a description of the pipeline without executing it. Construction cost is O(1) regardless of stream size.

Terminal Operation Cost

Terminal operations (toList, foldLeft, count) execute the full pipeline. Each element pull involves:

1. A VTask evaluation (virtual thread fork and join)
2. Pattern matching on the Step ADT (Emit, Skip, Done)
3. Any user-supplied transformation functions

  Per-Element Cost Breakdown
  ══════════════════════════

  Consumer calls pull()
       │
       ▼
  ┌─────────────────────┐
  │  VTask evaluation   │ ◀── dominant cost for simple transforms
  │  (virtual thread    │     (~microseconds)
  │   fork and join)    │
  └──────────┬──────────┘
             │
             ▼
  ┌─────────────────────┐
  │  Step pattern match │ ◀── near zero (ADT dispatch)
  │  Emit / Skip / Done │
  └──────────┬──────────┘
             │
             ▼
  ┌─────────────────────┐
  │  User function      │ ◀── depends on workload
  │  (map, filter, etc.)│     trivial: ~nanoseconds
  └──────────┬──────────┘     I/O: ~milliseconds (dominates)
             │
             ▼
        Next pull

The per-element cost is dominated by the VTask overhead for simple transformations. For I/O-bound operations, the virtual thread overhead is negligible compared to I/O latency.

Parallel Processing

Parallel operations add overhead for StructuredTaskScope management but provide significant throughput improvements for I/O-bound workloads:

For CPU-bound operations, parallelism beyond the number of available processors provides no benefit and may decrease performance due to scheduling overhead.

Chunking

Chunking reduces per-element overhead by amortising the VTask/virtual-thread cost across a batch:

  Element-by-element                   chunk(10) + batch
  ════════════════════                 ════════════════════

  e₁ ──▶ VTask ──▶ r₁                 e₁ ─┐
  e₂ ──▶ VTask ──▶ r₂                 e₂  │
  e₃ ──▶ VTask ──▶ r₃                 e₃  │
  e₄ ──▶ VTask ──▶ r₄                 ... ├──▶ 1 VTask ──▶ [r₁..r₁₀]
  ...                                  e₉  │
  e₁₀──▶ VTask ──▶ r₁₀                e₁₀─┘

  10 VTask forks                       1 VTask fork
  10× virtual thread overhead          1× virtual thread overhead

Larger chunk sizes reduce overhead but increase latency for the first result.

VStream vs Java Stream

Guidance:

• Use Java Stream for in-memory data transformations where effects are not needed
• Use VStream when your pipeline involves I/O, needs composable error handling, or benefits from virtual thread integration
• For simple map/filter/collect on lists, Java Stream is faster
• For I/O-bound pipelines with concurrent element processing, VStream with parEvalMap is more capable

Optimisation Tips

Minimise Pipeline Depth

Each combinator adds a layer of indirection. For hot paths, consider combining operations:

// Prefer: single map with combined logic
stream.map(x -> (x + 1) * 2)

// Over: multiple chained maps
stream.map(x -> x + 1).map(x -> x * 2)

Use Appropriate Chunk Sizes

For batch I/O operations, chunk size should balance between:

• Larger chunks: fewer VTask evaluations, higher throughput
• Smaller chunks: lower memory usage, faster first-result latency

Choose Concurrency Wisely

Over-provisioning concurrency wastes resources. Under-provisioning leaves throughput on the table. Start with the recommendations in the parallel operations guide and measure.

Previous: Parallel Operations Next: Writer