streambuffer CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

mvn compile          # Compile
mvn test             # Run all tests with coverage
mvn package          # Build JAR
mvn install -Dgpg.skip=true  # Install to local repo without GPG signing

Run a single test:

mvn test -Dtest=StreamBufferTest#testSimpleRoundTrip

Run mutation tests (the test-compile prefix is required — see the PIT policy):

mvn test-compile org.pitest:pitest-maven:mutationCoverage

Run JMH benchmarks:

JMH benchmarks live in src/test/java/net/ladenthin/streambuffer/benchmark/ (e.g. StreamBufferThroughputBenchmark). They are not executed by mvn test; invoke them directly via the exec-maven-plugin whose default mainClass is org.openjdk.jmh.Main:

# All benchmarks
mvn test-compile exec:java

# Filter by regex (class or method name)
mvn test-compile exec:java -Dexec.args="StreamBufferThroughput"

# Allocation profile (built-in, no extra setup)
mvn test-compile exec:java -Dexec.args="StreamBufferThroughput -prof gc"

# CPU profile via async-profiler (set ASYNC_PROFILER_LIB to libasyncProfiler.so)
mvn test-compile exec:java \
  -Dexec.args="StreamBufferThroughput -prof async:libPath=$ASYNC_PROFILER_LIB;output=flamegraph"

-prof gc reports gc.alloc.rate.norm (bytes allocated per op) — useful for spotting hidden allocations on the read/write hot paths. -prof async produces flamegraphs and requires async-profiler installed locally; CI does not run it.

mvn test also runs:

• jqwik properties (StreamBufferProperties) — picked up by Surefire as a JUnit 6 engine.
• Lincheck linearizability test (StreamBufferLincheckTest) over the non-blocking subset (write, available, close, isClosed).

Opt-in jcstress concurrency stress tests:

mvn -Pjcstress test

jcstress tests under net.ladenthin.streambuffer.jcstress live behind the jcstress profile. The profile binds exec-maven-plugin to the test phase to run the jcstress harness in a forked JVM (-m default). Off by default because the harness needs annotation-processor-generated test resources that are skipped by -DskipTests / -Dmaven.test.skip=true (would otherwise NPE) and because the run is slow.