[GR-55211] Update graal JIT compiler docs

PullRequest: graal/18252

Author: Bernard Horan

docs/reference-manual/java/Operations.md

@@ -14,8 +14,9 @@ The first thing to confirm when measuring performance is that the Java Virtual M
 
 GraalVM is configured to use the Graal JIT compiler as the top tier compiler by default.
 
-To enable the Graal JIT compiler for use in the [Java HotSpot Virtual Machine](https://docs.oracle.com/en/java/javase/22/vm/java-virtual-machine-technology-overview.html), use the `-XX:+UseGraalJIT` option.
+To enable the Graal JIT compiler for use in the [Java HotSpot Virtual Machine](https://docs.oracle.com/en/java/javase/23/vm/java-virtual-machine-technology-overview.html){:target="_blank"}, use the [`-XX:+UseGraalJIT`](https://download.java.net/java/early_access/jdk23/docs/specs/man/java.html#enabling-the-graal-jit-compiler){:target="_blank"} option.
 (The `-XX:+UseGraalJIT` option has to be used together with the `-XX:+UnlockExperimentalVMOptions` option that unlocks this experimental integration.)
+
 The following example runs the Java application `com.example.myapp` with the Graal JIT compiler enabled:
 
 ```shell
@@ -33,18 +34,18 @@ Using "Graal Enterprise compiler with Truffle extensions" loaded from a PGO opti
 
 Optimizing a JVM-based application is a science in itself.
 Compilation may not even be a factor in the case of poor performance as the problem may lie in any other part of the JVM (I/O, garbage collection, threading, and so on), or in a poorly written application, or third-party library code.
-For this reason, it is  worth employing the [JDK Mission Control](https://www.oracle.com/java/technologies/jdk-mission-control.html) tool chain to diagnose your application's behavior.
+For this reason, it is  worth employing the [JDK Mission Control](https://www.oracle.com/java/technologies/jdk-mission-control.html){:target="_blank"} toolchain to diagnose your application's behavior.
 
 You can also compare performance against the native top-tier compiler in the JVM by adding `-XX:-UseJVMCICompiler` to the command line.
 
 If you observe a significant performance regression when using the Graal JIT compiler, please open an issue on GitHub.
 Attach a Java Flight Recorder log and instructions to reproduce the issue—this makes investigation easier and thus increases the chances of a fix.
-Even better is if you can submit a [JMH](http://openjdk.java.net/projects/code-tools/jmh/) benchmark that represents the hottest parts of your application (as identified by a profiler).
+Even better is if you can submit a [JMH](http://openjdk.java.net/projects/code-tools/jmh/){:target="_blank"} benchmark that represents the hottest parts of your application (as identified by a profiler).
 This allows us to quickly pinpoint absent optimization opportunities or to provide suggestions on how to restructure your code to avoid or reduce performance bottlenecks.
 
 ## Troubleshooting the Graal JIT Compiler
 
-If you spot a security vulnerability, please do **not** report it via GitHub Issues or the public mailing lists, but via the process outlined in the [Reporting Vulnerabilities guide](https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html).
+If you spot a security vulnerability, please do **not** report it via GitHub Issues or the public mailing lists, but via the process outlined in the [Reporting Vulnerabilities guide](https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html){:target="_blank"}.
 
 ### Compilation Exceptions
 
@@ -57,7 +58,7 @@ In this case, just before the JVM exits, all diagnostic output captured during r
 Graal diagnostic output saved in /Users/demo/graal-dumps/1499768882600/graal_diagnostics_64565.zip
 ```
 
-You can then attach the ZIP file to an issue on [GitHub](https://github.com/oracle/graal/issues).
+You can then attach the ZIP file to an issue on [GitHub](https://github.com/oracle/graal/issues){:target="_blank"}.
 
 As well as `Silent` and `Diagnose`, the following values for `graal.CompilationFailureAction` are available:
 * `Print`: prints a message and stack trace to the console but does not perform recompilation.
@@ -85,22 +86,22 @@ jdk.graal.compiler.core.gen.NodeLIRBuilder.matchComplexExpressions(Ljava/util/Li
 
 The next two frames in the stack were interpreted (`j`).
 The location of the crash is also often indicated near the top of the file with something like this:
-```s
+```
 # Problematic frame:
 # J 761 JVMCI jdk.graal.compiler.core.gen.NodeLIRBuilder.matchComplexExpressions(Ljava/util/List;)V (299 bytes) @ 0x0000000108a2fc01 [0x0000000108a2fac0+0x141] (null)
 ```
 
 In this example, there is probably an error in the code produced by the Graal JIT compiler for `NodeLIRBuilder.matchComplexExpressions`.
 
-When filing an issue on [GitHub](https://github.com/oracle/graal/issues) for such a crash, you should first attempt to reproduce the crash with extra diagnostics enabled for the compilation of the problematic method.
+When filing an issue on [GitHub](https://github.com/oracle/graal/issues){:target="_blank"} for such a crash, you should first attempt to reproduce the crash with extra diagnostics enabled for the compilation of the problematic method.
 In this example, you would add the following options to your command line:
 ```shell
 -Djdk.graal.MethodFilter=NodeLIRBuilder.matchComplexExpressions, -Djdk.graal.Dump=:2
 ```
 
-These options are described in more detail [here](https://github.com/oracle/graal/blob/master/compiler/docs/Debugging.md).
+These options are described in more detail in the [compiler debugging documentation](https://github.com/oracle/graal/blob/master/compiler/docs/Debugging.md){:target="_blank"}.
 In brief, these options tell the Graal JIT compiler to capture snapshots of its state at verbosity level 2 while compiling any method named `matchComplexExpressions` in a class with a simple name of `NodeLIRBuilder`.
-The complete format of the `MethodFilter` option is described in [MethodFilterHelp.txt](https://github.com/oracle/graal/blob/master/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/debug/doc-files/MethodFilterHelp.txt).
+The complete format of the `MethodFilter` option is described in [MethodFilterHelp.txt](https://github.com/oracle/graal/blob/master/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/debug/doc-files/MethodFilterHelp.txt){:target="_blank"}.
 
 Quite often, the crash location does not exist directly in the problematic method mentioned in the crash log but comes from an inlined method.
 
@@ -148,7 +149,7 @@ ls -l /Users/demo/graal-dumps/1499768882600
 -rw-r--r--  1 demo  staff  12600725 Jul 13 11:46 HotSpotCompilation-791[NodeLIRBuilder.matchComplexExpressions(List)].bgv
 -rw-r--r--  1 demo  staff   1727409 Jul 13 11:46 HotSpotCompilation-791[NodeLIRBuilder.matchComplexExpressions(List)].cfg
 ```
-You should attach a ZIP file of this directory to an issue on [GitHub](https://github.com/oracle/graal/issues).
+You should attach a ZIP file of this directory to an issue on [GitHub](https://github.com/oracle/graal/issues){:target="_blank"}.
 
 ### Related Documentation
 

docs/reference-manual/java/Options.md

@@ -54,7 +54,7 @@ To see the available configurations, supply the value `help` to this option.
 ### Performance Tuning Options
 
 * `-Djdk.graal.Vectorization={ true | false }`: To disable the auto vectorization optimization (only available in Oracle GraalVM). (Default: `true`.)
-* `-Djdk.graal.OptDuplication={ true | false }`: To disable the [path duplication optimization](http://ssw.jku.at/General/Staff/Leopoldseder/DBDS_CGO18_Preprint.pdf) (only available in Oracle GraalVM). (Default: `true`.)
+* `-Djdk.graal.OptDuplication={ true | false }`: To disable the [path duplication optimization](http://ssw.jku.at/General/Staff/Leopoldseder/DBDS_CGO18_Preprint.pdf){:target="_blank"} (only available in Oracle GraalVM). (Default: `true`.)
 * `-Djdk.graal.TuneInlinerExploration=<value>`: To tune for better peak performance or faster warmup.
 It automatically adjusts values governing the effort spent during inlining. The value of the option is a float clamped between `-1` and `1` inclusive. Anything below `0` reduces inlining effort and anything above `0` increases inlining effort. In general, peak performance is improved with more inlining effort while less inlining effort improves warmup (albeit to a lower peak). Note that this option is only a heuristic and the optimal value can differ from application to application (only available in Oracle GraalVM).
 

docs/reference-manual/java/README.md

@@ -7,35 +7,35 @@ permalink: /reference-manual/java/
 
 # GraalVM as a Java Virtual Machine
 
-GraalVM is based on the [Java HotSpot Virtual Machine](https://docs.oracle.com/en/java/javase/22/vm/java-virtual-machine-technology-overview.html), so any application that runs on the Java HotSpot Virtual Machine will also on GraalVM.
+GraalVM is based on the [Java HotSpot Virtual Machine](https://docs.oracle.com/en/java/javase/23/vm/java-virtual-machine-technology-overview.html), so any application that runs on the Java HotSpot Virtual Machine will also on GraalVM.
 
 GraalVM includes an advanced compiler written in Java, known as the _Graal compiler_.
 At runtime, just like any other Java Virtual Machine (JVM), GraalVM loads an application and analyzes its code to detect performance bottlenecks, or _hot spots_. 
 GraalVM passes the performance-critical code to the Graal just-in-time (JIT) compiler, which compiles it to machine code and then returns it.
 
 The Graal compiler can improve the efficiency and the speed of applications written in Java, Scala, Kotlin, or other JVM languages through its unique approaches to code analysis and optimization.
 For example, it assures performance advantages for highly-abstracted applications due to its ability to remove costly object allocations.
-For more information, see the [platform-independent compiler optimizations in GraalVM Community Edition](https://github.com/oracle/graal/blob/master/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/phases/CEOptimization.java){:target="_blank"}.
+See the [`CEOptimization enum`](https://github.com/oracle/graal/blob/master/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/phases/CEOptimization.java){:target="_blank"} in the GraalVM Community Edition GitHub repository for more information about platform-independent compiler optimizations.
 
-> The Graal (JIT) compiler is now also integrated with the [Java HotSpot Virtual Machine](https://docs.oracle.com/en/java/javase/22/vm/java-virtual-machine-technology-overview.html). 
-To find out more, see [Graal Compiler](compiler.md).
+> The Graal (JIT) compiler is now also integrated with the Java HotSpot Virtual Machine.
+To find out more, see the section [Graal Compiler](compiler.md).
 
 ## Interoperability
 
 GraalVM also includes the [Truffle language implementation framework](../../../truffle/docs/README.md)—a library, written in Java—to build interpreters for programming languages, which then run on GraalVM.
 These "Graal languages" can consequently benefit from the optimization possibilities of the Graal compiler.
 The pipeline for such compilation is:
 
-* The Truffle framework code and data (Abstract Syntax Trees) is partially evaluated to produce a compilation graph. When such an Abstract Syntax Tree (AST) is "hot" (that is, called many times), it is scheduled for compilation by the compiler.
-* The compilation graph is optimized by the Graal compiler to produce machine code.
-* JVMCI installs this machine code in the JVM's code cache.
-* The AST will automatically redirect execution to the installed machine code once it is available.
+1. The Truffle framework code and data represented by Abstract Syntax Trees (ASTs) are partially evaluated to produce a compilation graph. When such an AST is "hot" (that is, called many times), it is scheduled for compilation by the compiler.
+2. The compilation graph is optimized by the Graal compiler to produce machine code.
+3. JVMCI installs this machine code in the JVM's code cache.
+4. The AST will automatically redirect execution to the installed machine code once it is available.
 
 See the [Polyglot Programming](../polyglot-programming.md) and [Embedding Languages](../embedding/embed-languages.md) guides for more information about interoperability with other programming languages.
 
 ## Ahead-of-time Compilation
 
-Besides the Truffle framework, GraalVM incorporates its compiler into an advanced ahead-of-time (AOT) compilation technology—[Native Image](../native-image/README.md)—which translates Java and JVM-based code into a native platform executable.
+Besides the Truffle framework, GraalVM incorporates its compiler into an advanced ahead-of-time (AOT) compilation technology—Native Image—which translates Java and JVM-based code into a native platform executable.
 These native executables start nearly instantaneously, are smaller, and consume less resources than their JVM counterparts, making them ideal for cloud deployments and microservices.
 For more information about AOT compilation, see [Native Image](../native-image/README.md).
 
@@ -45,3 +45,4 @@ For more information about AOT compilation, see [Native Image](../native-image/R
 - [Graal JIT Compiler Configuration](Options.md)
 - [Graal JIT Compiler Operations Manual](Operations.md)
 - [Native Image](../native-image/README.md)
+- [JDK tool reference](https://docs.oracle.com/pls/topic/lookup?ctx=javase23&id=java_tool_reference){:target="_blank"}

docs/reference-manual/java/compiler.md

@@ -9,21 +9,19 @@ redirect_from: /reference-manual/compiler/
 # Graal Compiler
 
 The Graal compiler is a dynamic compiler, written in Java, that transforms bytecode into machine code.
-The Graal just-in-time (JIT) compiler is integrated with the [Java HotSpot Virtual Machine](https://docs.oracle.com/en/java/javase/22/vm/java-virtual-machine-technology-overview.html) and [GraalVM](README.md).
-(The open source code of the Graal JIT compiler is available on [GitHub](https://github.com/oracle/graal/tree/master/compiler).)
-
+The Graal just-in-time (JIT) compiler is integrated with the Java HotSpot Virtual Machine and GraalVM.
+See [Java Virtual Machine Guide](https://docs.oracle.com/en/java/javase/23/vm/java-virtual-machine-technology-overview.html){:target="_blank"} and the section [GraalVM as a Virtual Machine](README.md) for more information.
+(The open source code of the Graal JIT compiler is available on [GitHub](https://github.com/oracle/graal/tree/master/compiler){:target="_blank"}.)
 
 ## Compiler Advantages
 
 The Graal JIT compiler provides optimized performance for applications running on a Java Virtual Machine (JVM) through unique approaches to code analysis and optimization.
 It includes multiple optimization algorithms (called “Phases”), such as aggressive inlining, polymorphic inlining, and others. 
 
-<!--
-    Add an anchor so that the JPG docs can link to a section on partial escape analysis.
--->
 <a id="partial-escape-analysis"></a>
-The Graal compiler can bring performance advantages for highly-abstracted programs. 
-For example, it includes a [partial-escape-analysis optimization](https://github.com/oracle/graal/blob/master/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/phases/CEOptimization.java#L176){:target="_blank"} that can remove the costly allocations of certain objects. 
+The Graal compiler can bring performance advantages for highly-abstracted programs.
+For example, it includes a partial-escape-analysis optimization that can remove the costly allocations of certain objects.
+See the value [`PartialEscapeAnalysis`](https://github.com/oracle/graal/blob/master/compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/phases/CEOptimization.java#L176){:target="_blank"} in the `CEOptimization enum` in the GraalVM GitHub repository for more information.
 The optimization determines when a new object is accessible outside a compilation unit and only allocates it on paths that "escape" the compilation unit (for example, if the object is passed as a parameter, stored in a field, or returned from a method). 
 This approach can greatly improve the performance of an application by reducing the number of heap allocations. 
 Code that uses more modern Java features such as Streams or Lambdas will see greater improvements in performance as this type of code involves a significant number of such non- or partially-escaping objects.
@@ -32,7 +30,8 @@ For more information on performance tuning, refer to [Graal JIT Compiler Configu
 
 ## Graph Compilation
 
-To run guest programming languages (namely JavaScript, Python, and Ruby) in the same runtime as the host JVM-based language, the compiler works with a language-independent intermediate graph representation between the source language and the machine code to be generated. (For more information on language interoperability, see [Interoperability](README.md#interoperability).)
+To run guest programming languages (namely JavaScript, Python, and Ruby) in the same runtime as the host JVM-based language, the compiler works with a language-independent intermediate graph representation between the source language and the machine code to be generated.
+(For more information on language interoperability, see [Interoperability](README.md#interoperability).)
 
 The graph can represent similar statements of different languages in the same way, such as "if" statements or loops, which makes it possible to mix languages in the same application.
 The Graal compiler can then perform language-independent optimization and generate machine code on this graph.