salvatorecampagna opened a new pull request, #16114: URL: https://github.com/apache/lucene/pull/16114
## TL;DR Documentation only PR. Clarifies the ownership convention for `Accountable.ramBytesUsed()` and notes that `getChildResources()` is a diagnostic accessor, not a deduplicated ownership tree. No behavior change. Posted as a draft to make the proposed javadoc wording concrete for review. Not requesting merge until the convention is settled. ## 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 sums `ramBytesUsed()` across multiple Accountable instances that share state, the same memory can be counted more than once. This PR adds an ownership-oriented convention to the javadoc: - 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. Report only the bytes actually owned, not the deep content of referenced storage that is not owned. - The reference itself (the pointer slot for a borrowed field) is part of the holder's own object layout and is naturally accounted via shallow size. - `getChildResources()` is diagnostic; summing `ramBytesUsed()` 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 on `ramBytesUsed()` with the ownership convention; extended javadoc on `getChildResources()` to note it is a diagnostic accessor and not sum-safe. Refs apache/lucene#16113. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
