Skip to content

Apache Lucene open-source search software

Clarify intent of Accountable#ramBytesUsed (#16000)

Luca Cavanna185440b56cc0
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
index 15c2db97b9d..2bc5b8abee6 100644
--- a/lucene/CHANGES.txt
+++ b/lucene/CHANGES.txt
@@ -331,6 +331,8 @@ Improvements
* GITHUB#15989: DocValuesRangeIterator always tries to use skipper-based block iteration
as its approximation. (Alan Woodward)
+* GITHUB#16000: Clarify that Accountable#ramBytesUsed() reports JVM heap memory only. (Luca Cavanna)
+
Optimizations
---------------------
* GITHUB#15861: Optimise PhraseScorer by short circuiting non competitive documents in TOP_SCORES mode. (Prithvi S)
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 fed289598dd..b8506f73527 100644
--- a/lucene/core/src/java/org/apache/lucene/util/Accountable.java
+++ b/lucene/core/src/java/org/apache/lucene/util/Accountable.java
@@ -20,13 +20,23 @@ import java.util.Collection;
import java.util.Collections;
/**
- * An object whose RAM usage can be computed.
+ * An object whose JVM heap memory usage can be computed.
+ *
+ * <p>Implementations should only account for memory allocated on the Java heap (i.e. memory managed
+ * by the JVM garbage collector). Off-heap resources such as memory-mapped files or native direct
+ * buffers should not be included; those should be tracked separately if needed (see e.g. {@link
+ * org.apache.lucene.codecs.KnnVectorsReader#getOffHeapByteSize}).
*
* @lucene.internal
*/
public interface Accountable {
- /** Return the memory usage of this object in bytes. Negative values are illegal. */
+ /**
+ * Returns an estimate of the JVM heap memory used by this object in bytes. The method name uses
+ * "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.
+ */
long ramBytesUsed();
/**