From 1d52460c685d4c71a7bec81dc5c4e80b37b53edc Mon Sep 17 00:00:00 2001 From: Salvatore Campagna Date: Sat, 23 May 2026 13:49:29 +0200 Subject: [PATCH 1/2] docs(util): clarify Accountable.ramBytesUsed() ownership semantics Document an ownership-oriented convention for Accountable implementations: report memory allocated for the object's lifetime, or released by its close() if applicable. Inputs received via constructors or factories may be borrowed, wrapped, sliced, or copied; implementations should report only the bytes they actually own, not the deep content of referenced storage they do not own. Also clarify that getChildResources() is a diagnostic accessor and not a deduplicated ownership tree: summing ramBytesUsed() across its elements is not generally sum-safe. Refs apache/lucene#16113. --- .../java/org/apache/lucene/util/Accountable.java | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/lucene/core/src/java/org/apache/lucene/util/Accountable.java b/lucene/core/src/java/org/apache/lucene/util/Accountable.java index b8506f73527d..7e6eeff46dd4 100644 --- a/lucene/core/src/java/org/apache/lucene/util/Accountable.java +++ b/lucene/core/src/java/org/apache/lucene/util/Accountable.java @@ -36,6 +36,16 @@ public interface Accountable { * "ram" for historical reasons; only JVM heap memory should be reported. Off-heap resources such * as memory-mapped files or native direct buffers should not be included. Negative values are * illegal. + * + *

Implementations are encouraged to follow an ownership-oriented convention: report memory + * allocated for this object's lifetime, or released by its {@code close()} method if applicable. + * Inputs received via constructors or factories may be borrowed, wrapped, sliced, or copied; + * implementations should report only the bytes they actually own, not the deep content of + * referenced storage they do not own. The reference itself (the pointer slot for a borrowed + * field) is part of this object's own layout and is naturally accounted via shallow size; what + * should not be added is the deep content of the referenced storage. Reporting the deep content + * of borrowed storage can lead to double counting when consumers sum across multiple Accountable + * instances that share state. */ long ramBytesUsed(); @@ -43,6 +53,10 @@ public interface Accountable { * Returns nested resources of this class. The result should be a point-in-time snapshot (to avoid * race conditions). * + *

This method is a diagnostic accessor intended for inspection and printing. The returned + * collection is not a deduplicated ownership tree; it may include borrowed or shared references. + * Summing {@link #ramBytesUsed()} across its elements is not generally sum-safe. + * * @see Accountables */ default Collection getChildResources() { From 062cc1828f49b0fe0998e899ec3a7681077bf84d Mon Sep 17 00:00:00 2001 From: Salvatore Campagna Date: Sat, 23 May 2026 14:21:05 +0200 Subject: [PATCH 2/2] docs(util): add CHANGES.txt entry for Accountable javadoc clarification The Lucene PR workflow requires a CHANGES.txt entry. Added under Lucene 10.5.0 -> Other since the change is documentation only and not breaking. Refs apache/lucene#16113, apache/lucene#16114. --- lucene/CHANGES.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt index fec56b110bc7..e34af834c90d 100644 --- a/lucene/CHANGES.txt +++ b/lucene/CHANGES.txt @@ -473,6 +473,10 @@ Bug Fixes Other --------------------- +* GITHUB#16114: Clarify Accountable.ramBytesUsed() ownership semantics. The javadoc now + recommends reporting only memory the object owns and notes that getChildResources() is + a diagnostic accessor, not a deduplicated ownership tree. (Salvatore Campagna) + * GITHUB#15586: Document that scoring and ranking may change across major Lucene versions, and that applications requiring stable ranking should explicitly configure Similarity. (Parveen Saini) * GITHUB#15764: Added simpler TestTesselator test in support of fix GITHUB#15731. (Craig Taverner)