Skip to content

docs(util): clarify Accountable.ramBytesUsed() ownership semantics #16114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
salvatorecampagna wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs(util): clarify Accountable.ramBytesUsed() ownership semantics #16114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d52460
docs(util): clarify Accountable.ramBytesUsed() ownership semantics
salvatore-campagna May 23, 2026
062cc18
docs(util): add CHANGES.txt entry for Accountable javadoc clarification
salvatore-campagna May 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions lucene/CHANGES.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
14 changes: 14 additions & 0 deletions lucene/core/src/java/org/apache/lucene/util/Accountable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,27 @@ 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.
*
* <p>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();

/**
* Returns nested resources of this class. The result should be a point-in-time snapshot (to avoid
* race conditions).
*
* <p>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<Accountable> getChildResources() {
Expand Down
Loading