RFR: 8345836: stable annotation documentation is incomplete
The javadoc for jdk.internal.vm.annotation.Stable is incomplete. The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly. The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently. This is a first cut. Please comment… ------------- Commit messages: - 8345836: stable annotation documentation is incomplete Changes: https://git.openjdk.org/leyden/pull/26/files Webrev: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8345836 Stats: 172 lines in 1 file changed: 135 ins; 0 del; 37 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26 PR: https://git.openjdk.org/leyden/pull/26
Hi John, a few comments.
A field may be annotated as "stable" to indicate that it is a <em>stable variable</em>, expected to change value at most once.
Saying "at most once" suggests that changing the value zero times is A+ reasonable behavior. But it's not reasonable, given the policy of treating only non-default values of stable variables as foldable. I think it would be better to say: "expected to change value exactly once." The strictness of this phrase (versus the looser "at most once") sets the stage as firmly as possible for the exhortations, later, against multiple assignment.
Fields which are declared {@code final} may also be annotated as stable. Since final fields already behave as stable values, (The phrase "stables values" should be "stable variables"; later, the phrase "stable value" should be "stable variable".)
I got a sense here that stable variables are the fundamental construct, but aren't they more limited? `static final int x = 0;` would be eligible for constant folding but `@Stable int y = 0;` would not. Zero may be an uninteresting value, but it's not quite as uninteresting and un-fold-worthy as false.
As very simple example, a boolean variable is constant-folded only when it is set to {@code true}. Even this simple behavior is sometimes useful for recording a permanent one-shot state change,
It's a little hard to figure out if "behavior" refers to the constant folding or the assignment-to-true. I also got the sense that the constant folding occurs _as an immediate result of_ the assignment. It might be better to spell out the perspective: "As a simple example of constant folding, the HotSpot VM may constant fold a boolean variable if the variable is `true`. This means that application code can record a permanent one-shot state change in such a way that the compiler can remove dead code associated with the initial state." I would also place this paragraph ahead of the story for array-typed stable variables. Alex On 12/9/2024 3:58 PM, John R Rose wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
-------------
Commit messages: - 8345836: stable annotation documentation is incomplete
Changes: https://git.openjdk.org/leyden/pull/26/files Webrev: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8345836 Stats: 172 lines in 1 file changed: 135 ins; 0 del; 37 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 63:
61: * if the consequent optimization is desired. 62: * <p> 63: * As a special case, if a stable field is declared as an array type
If `array` is a stable array field, is `array.length` treated as an independent stable variable? ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1877495405
On Tue, 10 Dec 2024 07:36:26 GMT, Per Minborg <pminborg@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 63:
61: * if the consequent optimization is desired. 62: * <p> 63: * As a special case, if a stable field is declared as an array type
If `array` is a stable array field, is `array.length` treated as an independent stable variable?
If `array` is a stable field, wouldn't `array.length` just be a (potentially compile time) constant? ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878426359
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 165:
163: * <p> 164: * After constant folding, the compiler can make use of may aspects of 165: * the object: Its dynamic type, its length (if it is an array), and
Ahh. Here is the answer to the `array.length` question. Good. ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1877506923
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
It might be worth mentioning that primitive types could be held in a wrapper class (rather than as a primitive value) if the default values are important to capture and constant-fold. Another thing that we could talk about when it comes to stable variables initialized outside `<init>` and `<clinit>` in a multi-threaded scenario is that code can use CAS operations when initializing the stable variable to uphold the update-at-most-once invariant and that readers can use acquire/release or volatile semantics when reading the stable variable. This ensures consistency across threads while still allowing VM optimizations. ------------- PR Comment: https://git.openjdk.org/leyden/pull/26#issuecomment-2530704189
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 164:
162: * VM. 163: * <p> 164: * After constant folding, the compiler can make use of may aspects of
Suggestion: * After constant folding, the compiler can make use of many aspects of ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1877760792
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 196:
194: * recent" value observed by the interpreter or less-optimized code. 195: * <p> 196: * For all these reasons, a user who bends the rules for a stable
I've cases in the JDK where a stable fields could, under race, be assigned to objects that are semantically equivalent, but whose identity is distinct. Would you say this is a good use of `@Stable` ? In FFM we took extra precaution and deduplicated the identity by using a concurrent hash map -- but is this required? ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1877767198
On Tue, 10 Dec 2024 10:02:04 GMT, Maurizio Cimadamore <mcimadamore@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 196:
194: * recent" value observed by the interpreter or less-optimized code. 195: * <p> 196: * For all these reasons, a user who bends the rules for a stable
I've cases in the JDK where a stable fields could, under race, be assigned to objects that are semantically equivalent, but whose identity is distinct. Would you say this is a good use of `@Stable` ? In FFM we took extra precaution and deduplicated the identity by using a concurrent hash map -- but is this required?
I think so; we have benign races for non-stable fields like `Class.reflectionFactory`. However, sometimes sharing the same object avoids redundant cache computation. It is ultimately a tradeoff between synchronization and lock overheads and the applicability of cache. ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878392882
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 130:
128: * any other context. This implies that a constructor may choose to 129: * initialize a stable variable, rather than "leaving it for later", 130: * and that initial will be safely published, as if the field were
"initial" -> "initial value" src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 165:
163: * <p> 164: * After constant folding, the compiler can make use of may aspects of 165: * the object: Its dynamic type, its length (if it is an array), and
"Its" -> "its". (no capital I needed) src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 215:
213: * some other internal proof of correctness (accounting for any 214: * possible racing API access), or by some appropriate disclaimer in 215: * the API about undefined behavior.
This caution/warning might be better at the top of the file. ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878235640 PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878240903 PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878249158
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 166:
164: * After constant folding, the compiler can make use of may aspects of 165: * the object: Its dynamic type, its length (if it is an array), and 166: * the values of its fields (if they are themselves constants, either
I wonder if this includes object identity, or the object's identity hash code - for example, published MethodType objects are all identity-based, and using their identity hash should be better than using their nominal hash code. ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878410313
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 111:
109: * treated in this way during AOT cache assembly, that fact must be 110: * clearly stated as a warning on the field declaration. If there is 111: * no such warning, maintainers can ignore this edge case.
The warning on the field declaration is a comment? As a follow on to this, should we define an additional annotation to carry that warning ie `@AssemblyTimeChangable`? (better naming to be bike shed) ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878433056
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 146:
144: * (or zero) value. Code which cannot prove proper ordering of 145: * initialization may use stable variables without performing the null 146: * (or zero) test. Code which omits the null (or zero) test should be
* (or zero) value. Code which cannot prove proper ordering of * initialization may use stable variables without performing the null * (or zero) test. Code which omits the null (or zero) test should be Do we want to say "may use without null check" or is there a missing "should not" in that sentence? ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878446302
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 78:
76: * declared as an array potentially defines a tree (of fixed depth 77: * <em>D</em>) containing many stable variables, with each such stable 78: * variable is independently considered for optimization. In this
Suggestion: * variable independently considered for optimization. In this ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878851183
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision: incorporate all review comments ------------- Changes: - all: https://git.openjdk.org/leyden/pull/26/files - new: https://git.openjdk.org/leyden/pull/26/files/ff94e0f5..273aa2e6 Webrevs: - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=01 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00-01 Stats: 191 lines in 1 file changed: 107 ins; 23 del; 61 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26 PR: https://git.openjdk.org/leyden/pull/26
Re: "A stable variable may be assigned its final value inside a class or object initializer" -- better to avoid "final value" since "final" is a property of variables -- prefer "permanent value" (as used elsewhere). "For example, declaring two stable fields of type {@code int} and {@code String} creates a pair of stable variables" -- here, the field declarations are "syntax" while the creation of stable variables is "semantics" ... as such, the declarations should lean on the syntactic device `@Stable` rather than the semantic concept of "stable field". Recommend: "For example, suppose a class has two non-final fields of type int and String. Annotating the field declarations with @Stable creates a pair of stable variables. The fields are initialized to zero and null, respectively, in the usual way, but storing a non-zero integer in the first field or a non-null reference in the second field will enable the VM to expect ..." Before "As an extended behavior," please insert a heading "Array-typed stable variables". Before "As very simple example", please insert a heading "Constant folding of stable variables". Before "Fields which are declared {@code final}", please insert a heading "`final` variables and stable variables". Please consider adding further headings. Alex On 12/11/2024 1:36 PM, John R Rose wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision:
incorporate all review comments
-------------
Changes: - all: https://git.openjdk.org/leyden/pull/26/files - new: https://git.openjdk.org/leyden/pull/26/files/ff94e0f5..273aa2e6
Webrevs: - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=01 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00-01
Stats: 191 lines in 1 file changed: 107 ins; 23 del; 61 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision: more edits, better examples, section headings ------------- Changes: - all: https://git.openjdk.org/leyden/pull/26/files - new: https://git.openjdk.org/leyden/pull/26/files/273aa2e6..6a2174cb Webrevs: - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=02 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=01-02 Stats: 72 lines in 1 file changed: 46 ins; 0 del; 26 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26 PR: https://git.openjdk.org/leyden/pull/26
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision: more edits, better examples, section headings ------------- Changes: - all: https://git.openjdk.org/leyden/pull/26/files - new: https://git.openjdk.org/leyden/pull/26/files/6a2174cb..36c5bec2 Webrevs: - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=03 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=02-03 Stats: 8 lines in 1 file changed: 1 ins; 0 del; 7 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26 PR: https://git.openjdk.org/leyden/pull/26
On Thu, 12 Dec 2024 08:13:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision:
more edits, better examples, section headings
For easier review, here is a rendered version of the most recent changes. It is a stand-alone HTML, so you won't get the nice style-sheet. https://cr.openjdk.org/~jrose/jvm/Stable.html ------------- PR Comment: https://git.openjdk.org/leyden/pull/26#issuecomment-2538260936
First paragraph: Both "initial default value" and "default initial value" appear, and I originally planned to just regularize the order of adjectives. But then I questioned whether "initial" adds value fast enough. The edits below, which involve dropping and replacing individual words, produce a smoother story IMO. "its initial default (null or zero) value" -> "its default value (null or zero)" "When the first value is stored into the field (assuming it is not a duplicate of the the field's default initial value), the VM may ..." -> "When the first value is stored into the field that is not the field's default value, the VM may ..." "Or is the user waiting until later to assign another value to the variable?" -> "Or is the user waiting until later to assign a permanent value to the variable?" "The VM does not systematically record stores of a default null (or primitive zero), so there is no way for the VM to decide if a default field value is an undisturbed initial default value" -> "The VM does not systematically record stores of a null (resp., zero) to a stable variable, so there is no way for the VM to decide if a field's current value is its undisturbed default value or has been overwritten with an intentionally stored null (resp., zero)." In the Example section: - The phrase "stable value" has crept in. - Is a _value_ constant-foldable? Or a _variable_? I think the latter. However, "constant-foldable string" appears more than once, suggesting the former. There are numerous other clauses in the text which muddy the issue -- I suggest taking a fine tooth comb over the text. - The "As a very simple example ..." paragraph is weird, coming after so many other examples. I think the best thing is to turn it into code. - The final paragraph about "mutually exclusive" and "never be part of public APIs" gives substantive advice about using stable variables that should not be buried in an examples section. I recommend moving this paragraph up to "Stable Variable Life Cycle" as a first step. Alex On 12/12/2024 1:03 AM, John R Rose wrote:
On Thu, 12 Dec 2024 08:13:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision:
more edits, better examples, section headings
For easier review, here is a rendered version of the most recent changes. It is a stand-alone HTML, so you won't get the nice style-sheet.
https://cr.openjdk.org/~jrose/jvm/Stable.html
-------------
PR Comment: https://git.openjdk.org/leyden/pull/26#issuecomment-2538260936
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision: incorporate Alex comments ------------- Changes: - all: https://git.openjdk.org/leyden/pull/26/files - new: https://git.openjdk.org/leyden/pull/26/files/36c5bec2..5070a26b Webrevs: - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=04 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=03-04 Stats: 35 lines in 1 file changed: 12 ins; 10 del; 13 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26 PR: https://git.openjdk.org/leyden/pull/26
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision: remove stray word ------------- Changes: - all: https://git.openjdk.org/leyden/pull/26/files - new: https://git.openjdk.org/leyden/pull/26/files/5070a26b..aa18de77 Webrevs: - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=05 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=04-05 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/leyden/pull/26.diff Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26 PR: https://git.openjdk.org/leyden/pull/26
On Thu, 9 Jan 2025 07:29:05 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision:
remove stray word
src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 41:
39: * to assume that no more significant changes will occur. This in 40: * turn enables the VM to optimize uses of the stable variable, treating 41: * them as constant values. This behavior is a useful building block
This in turn enables the VM to optimize uses of the stable variable, treating them as constant values.
A mistake I often see people make, is thinking that `@Stable` will always allow the JIT to directly use the value of an instance field. But, this of course depends on the instance holding the field being a constant as well. I feel like this could be stated more explicitly in this text. Maybe something along the lines of: A instance field load operation has as input an object instance, and as output the value of a particular field. There are two requirements for constant folding such a load operation: 1) the object instance is a constant. 2) the field's value will not change in the future. The `@Stable` annotation influences _only_ the second condition. It is the responsibility of the user of this annotation to make sure that a load operation on a field annotated with `@Stable` has a constant object instance as input, if constant folding of the load operation is desired as a result. ------------- PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1908718864
On Thu, 9 Jan 2025 07:29:05 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
John R Rose has updated the pull request incrementally with one additional commit since the last revision:
remove stray word
Looks good. ------------- Marked as reviewed by vlivanov (Committer). PR Review: https://git.openjdk.org/leyden/pull/26#pullrequestreview-2540667322
On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose@openjdk.org> wrote:
The javadoc for jdk.internal.vm.annotation.Stable is incomplete.
The existing documentation gives an over-simple user model, and does not explain how it is implemented. Proposed new documentation will detail how the annotation is implemented, and how it may be used correctly.
The improved documentation will makes it easier for JDK programmers to use the annotation more aggressively, and more confidently.
This is a first cut. Please comment…
This pull request has been closed without being integrated. ------------- PR: https://git.openjdk.org/leyden/pull/26
participants (9)
-
Alex Buckley
-
Chen Liang
-
Dan Heidinga
-
John R Rose
-
Jorn Vernee
-
Maurizio Cimadamore
-
Per Minborg
-
Roger Riggs
-
Vladimir Ivanov