streambuffer: Instructions file for Claude Code

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) — a JUnit Platform engine; Surefire runs the class only because pom.xml adds **/*Properties.java to its include patterns (until 2026-10-19 it ran in no build, since the name matches none of Surefire's defaults). Under -Pjml-rac they run with 100 tries instead of 1000 (jqwik.tries.default).
• Lincheck linearizability test (StreamBufferLincheckTest) over the non-blocking subset (write, available, close, isClosed).