Add trim lifecycle observability, statistics tracking, and allocation sizing

[bernardladenthin]

Summary

This PR enhances StreamBuffer with comprehensive observability and control features for the trim operation, adds cumulative I/O statistics tracking, and introduces configurable allocation sizing for trim consolidation. The changes improve visibility into buffer behavior and provide fine-grained control over memory consolidation.

Key Changes

• Trim Lifecycle Signals: Added addTrimStartSignal(), removeTrimStartSignal(), addTrimEndSignal(), and removeTrimEndSignal() methods to observe when trim cycles begin and complete. Uses the same semaphore-based notification pattern as general modification signals.

• Statistics Tracking: Introduced three new volatile fields to track cumulative I/O:

  • getTotalBytesWritten() — cumulative bytes written by user operations (excludes internal trim)
  • getTotalBytesRead() — cumulative bytes consumed by user reads (excludes internal trim)
  • getMaxObservedBytes() — peak value of buffered bytes ever observed
  • Statistics are updated only during user I/O, not during trim operations

• Configurable Trim Allocation Size: Added setMaxAllocationSize(long) and getMaxAllocationSize() to limit the size of individual byte arrays produced during trim consolidation. When availableBytes > maxAllocationSize, trim produces multiple smaller chunks instead of one large array.

• Trim Execution Observability: Added isTrimRunning() volatile method to check whether a trim cycle is currently executing.

• Smart Trim Skipping: Trim now automatically skips consolidation when the resulting chunk count would not be smaller than the current deque size, preventing repeated no-op trims when maxAllocationSize is very small.

• Enhanced API Reference: Updated documentation with new methods, clarified that getBufferSize() is legacy, and added getBufferElementCount() as the synchronized alternative.

• Test Framework Update: Updated test documentation to reflect migration from JUnit 4 with DataProviderRunner to JUnit 5 (JUnit Jupiter).

Implementation Details

• Five new volatile state fields added: maxAllocationSize, isTrimRunning, maxObservedBytes, totalBytesWritten, totalBytesRead
• Trim observer signals stored in separate CopyOnWriteArrayList instances for thread-safe concurrent access
• Statistics counters check isTrimRunning before updating to ensure only user I/O is counted
• Trim consolidation logic enhanced to produce multiple chunks when allocation size limit is exceeded
• Comprehensive test coverage added for all new features including concurrent scenarios and edge cases

https://claude.ai/code/session_015f5tWNnFyhBYoyZAt3EC8i