docs(util): clarify Accountable.ramBytesUsed() ownership semantics#16114
Draft
salvatorecampagna wants to merge 2 commits into
Draft
docs(util): clarify Accountable.ramBytesUsed() ownership semantics#16114salvatorecampagna wants to merge 2 commits into
Accountable.ramBytesUsed() ownership semantics#16114salvatorecampagna wants to merge 2 commits into
Conversation
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#16113.
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#16113, apache#16114.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Documentation only PR. Clarifies the ownership convention for
Accountable.ramBytesUsed()and notes thatgetChildResources()is a diagnostic accessor, not a deduplicated ownership tree. No behavior change.Summary
Accountable.ramBytesUsed()is currently documented as "an estimate of the bytes used by this object" without saying whether bytes from referenced objects are included. Implementations vary: some count everything reachable, others count only owned state. When external code sumsramBytesUsed()across multipleAccountableinstances that share state, the same memory can be counted more than once.This PR adds an ownership-oriented convention to the javadoc:
close()if applicable.getChildResources()is diagnostic; summingramBytesUsed()across its elements is not generally sum-safe.The convention is already followed informally in parts of the codebase. This PR documents it so future implementers and reviewers have a clear contract to apply.
Changes
Accountable.java: extended javadoc onramBytesUsed()with the ownership convention; extended javadoc ongetChildResources()to note it is a diagnostic accessor and not sum-safe.Refs #16113.