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) 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