[GR-68914] Review Truffle Deoptimization Cycle Patterns documentation.

PullRequest: graal/21941

Author: olyagpl

truffle/docs/CloseOnGc.md

@@ -1,8 +1,17 @@
-## Automatic Close of Unreachable Context and Engine Objects in Polyglot API
+---
+layout: docs
+toc_group: truffle
+link_title: Automatic Close of Unreachable Context and Engine Objects in Polyglot API
+permalink: /graalvm-as-a-platform/language-implementation-framework/CloseOnGc/
+---
 
-Beginning with Polyglot version 24.2.0, `Context` and `Engine `objects are automatically closed when they are no longer strongly referenced. This feature ensures that unreachable `Context` and `Engine` instances are correcly cleaned up to minimize memory leaks. However, it remains highly recommended to manage the lifecycle of `Context` and `Engine` explicitly, ideally using a try-with-resources statement, rather than relying on garbage collection for this purpose.
+# Automatic Close of Unreachable Context and Engine Objects in Polyglot API
 
-### Context Lifecycle Management
+As of Polyglot version 24.2.0, `Context` and `Engine `objects are automatically closed when they are no longer strongly referenced.
+This feature ensures that unreachable `Context` and `Engine` instances are correctly cleaned up to minimize memory leaks.
+However, it remains highly recommended to manage the lifecycle of `Context` and `Engine` explicitly, ideally using a try-with-resources statement, rather than relying on garbage collection for this purpose.
+
+## Context Lifecycle Management
 
 A `Context` instance is eligible for automatic closure when no strong references to it remain. These references can include the following:
 
@@ -11,22 +20,26 @@ A `Context` instance is eligible for automatic closure when no strong references
 * Active polyglot threads or any host thread that has explicitly entered the `Context`. A `Context` that is explicitly [entered](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.html#enter()) will not be garbage-collected until it is explicitly [left](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.html#leave()).
 * Inner `Context` objects, as inner contexts prevent their parent contexts from being closed if they remain reachable.
 
-When any of these conditions hold, the `Context` instance remains active and will not be garbage-collected and closed. The presence of active system threads does not prevent a `Context` from being closed.
-
+When any of these conditions hold, the `Context` instance remains active and will not be garbage-collected and closed.
+The presence of active system threads does not prevent a `Context` from being closed.
 
-### Engine Lifecycle Management
+## Engine Lifecycle Management
 
-The `Engine` object follows a similar approach to lifecycle management. An `Engine` will only be closed when it no longer has any strong references to it, such as:
+The `Engine` object follows a similar approach to lifecycle management.
+An `Engine` will only be closed when it no longer has any strong references to it, such as:
 
 * Direct references to the `Engine`.
 * Strong references to `Language`, `Instrument`, or `ExecutionListener` instances that were obtained from the `Engine`.
 
-Furthermore, an `Engine` cannot be closed if there is an active `Context` within it or if any `Context` objects that uses this `Engine` remain reachable. Similar to `Context` objects, the presence of active system threads does not interfere with the automatic closure of an `Engine`.
+Furthermore, an `Engine` cannot be closed if there is an active `Context` within it or if any `Context` objects that uses this `Engine` remain reachable.
+Similar to `Context` objects, the presence of active system threads does not interfere with the automatic closure of an `Engine`.
 
-### TruffleContext and Inner Contexts
+## TruffleContext and Inner Contexts
 
-In scenarios where a language implementation creates inner contexts using [TruffleLanguage.Env.newInnerContextBuilder()](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.Env.html#newInnerContextBuilder(java.lang.String...)), both the Polyglot API `Context` representing this inner context and the `TruffleContext` must be unreachable to enable automatic closure. This situation is illustrated in the diagram below, showing an engine with one top-level context and one inner context. Strong references are represented by solid lines, and weak references by dashed lines.
+In scenarios where a language implementation creates inner contexts using [TruffleLanguage.Env.newInnerContextBuilder()](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.Env.html#newInnerContextBuilder(java.lang.String...)), both the Polyglot API `Context` representing this inner context and the `TruffleContext` must be unreachable to enable automatic closure.
+This situation is illustrated in the diagram below, showing an engine with one top-level context and one inner context. Strong references are represented by solid lines, and weak references by dashed lines.
 
 ![Context References](context_references.png "Context References")
 
-When an inner `Context` is no longer referenced by the embedder, and the corresponding `TruffleContext` instance is no longer referenced by its language implementation, weak references from `PolyglotContext` to `Context` and `TruffleContext` are added to a reference queue. During the next lifecycle event (such as when a new context is created or closed), this queue is processed, and any unreachable context is closed automatically.
+When an inner `Context` is no longer referenced by the embedder, and the corresponding `TruffleContext` instance is no longer referenced by its language implementation, weak references from `PolyglotContext` to `Context` and `TruffleContext` are added to a reference queue.
+During the next lifecycle event (such as when a new context is created or closed), this queue is processed, and any unreachable context is closed automatically.

truffle/docs/DeoptCyclePatterns.md

@@ -1,12 +1,18 @@
-## Deoptimization Cycle Patterns
+---
+layout: docs
+toc_group: truffle
+link_title: Deoptimization Cycle Patterns
+permalink: /graalvm-as-a-platform/language-implementation-framework/DeoptCyclePatterns/
+---
 
-Since version 25, Truffle has included an automatic deoptimization cycle detection feature, which is a powerful tool
-for identifying existing deoptimization cycles. The goal of this document is to help prevent deoptimization cycles.
-To that end, it describes a number of common patterns that can cause deoptimization cycles and should therefore be avoided.
+# Deoptimization Cycle Patterns
 
-### Always Deopt Node
+As of GraalVM for JDK 25, the Truffle framework includes an **automatic deoptimization cycle detection feature**, which is a powerful tool for identifying existing deoptimization cycles.
+The goal of this document is to help prevent deoptimization cycles by describing common patterns that can lead to such cycles, which should be avoided.
 
-The following is the simplest pattern that causes a deoptimization cycle:
+### Always Deoptimizing Node
+
+One of the simplest patterns that causes a deoptimization cycle is as follows:
 
 ```java
 class AlwaysDeoptNode extends RootNode {
@@ -18,9 +24,9 @@ class AlwaysDeoptNode extends RootNode {
 }
 ```
 
-When the above code is compiled, it deoptimizes and invalidates on the first execution. The same occurs with each subsequent compilation and execution.
-This is an extreme example, and it's hard to imagine how the code could be useful for anything other than testing purposes,
-but it is a clear cause of unbounded repeated deoptimization—that is, a deoptimization cycle.
+When the above code is compiled, it deoptimizes and invalidates on the first execution.
+The same occurs with each subsequent compilation and execution.
+This is an extreme example, and it is hard to imagine how the code could be useful for anything other than testing purposes, but it is a clear cause of unbounded repeated deoptimization—that is, a deoptimization cycle.
 
 ### Invalid Argument Profiling Node
 
@@ -43,14 +49,15 @@ class InvalidArgumentProfilingNode extends RootNode {
 }
 ```
 
-The number of deoptimizations and invalidations in the above code is unbounded because the profiled argument can keep changing
-with no limit on the number of these changes. Consequently, there is no bound on the number of deoptimizations.
+The number of deoptimizations and invalidations in the above code is unbounded because the profiled argument can keep changing with no limit on the number of these changes.
+Consequently, there is no bound on the number of deoptimizations.
 
-A possible solution to this problem would be to use the `IntValueProfile`, which caches the value only once and switches to a generic state when the value changes.
+A possible solution to this problem would be to use `IntValueProfile`, which caches the value only once and switches to a generic state when the value changes.
 
 ### Stabilize Late Node
 
-The following code does not cause a true deoptimization cycle. It eventually stabilizes, but it does so so late that the deoptimization cycle detection tool might report a deoptimization cycle:
+The following code does not cause a true deoptimization cycle.
+It eventually stabilizes, but stabilization occurs so late that the deoptimization cycle detection tool might still report a cycle:
 
 ```java
 class StabilizeLateNode extends RootNode {
@@ -88,27 +95,29 @@ class StabilizeLateNode extends RootNode {
 }
 ```
 
-The above code must be executed 20 times with an argument different from `cachedValue` in order for `seenCount` to reach 20 and
-prevent further deoptimization. In theory, the code could be compiled and deoptimized for each value of `seenCount` below 20, i.e., twenty times.
+After 20 consecutive executions where the argument `arg` is different from `cachedValue`, the variable `seenCount` reaches 20. At this point, deoptimizations stop.
+Until then, the code may be compiled and deoptimized once for each `seenCount` value below 20—up to twenty times.
 Since deoptimization cycle detection is enabled by default after 15 compilations, it could be triggered by this late-stabilizing code.
 
 The solution to this problem is to ensure that the optimizations stabilize more quickly.
 
 ### Compilation Final Field of a Non-Constant Object
 
-Truffle compilation final fields are a powerful optimization tool and are often used to control speculations. For example, they are used in conditions
-checking whether a certain specialized piece code is valid for the current input. When it is not, and the code is compiled, they cause deoptimization
-and invalidation which allows the code to re-specialize before the next compilation. However, this usage must follow one basic rule:
+Truffle compilation final fields are a powerful optimization tool, often used to control speculations.
+For example, they are used in conditions checking whether a certain specialized piece of code is valid for the current input.
+When it is not, the compiled code is deoptimized and invalidated. This allows the code to re-specialize and recompile with the updated assumption.
+However, this usage must follow one key rule:
 
 * The number of possible deoptimizations (and invalidations) caused by the condition involving a compilation final field should be small. As seen in the previous examples, failing to follow this rule can lead to issues.
 
-Extra caution must be taken when the object containing the compilation field is not a partial evaluation (PE) constant because, in that case, the field is not compilation-final, and reading it translates to a normal field read. This makes it more difficult to reason about the number of possible deoptimizations caused by a condition involving the field.
+Extra caution must be taken when the object containing the compilation field is not a partial evaluation (PE) constant because, in that case, the field is not compilation-final, and reading it translates to a normal field read.
+This makes it more difficult to reason about the number of possible deoptimizations caused by a condition involving the field.
 
 The following examples demonstrate what can happen if this caution is not exercised.
 
 #### Example 1: Non-Constant Language Context
 
-The following code shows repeated deoptimization caused by the initialization of each fresh language context:
+The following code shows repeated deoptimization caused by the initialization of each new language context:
 
 ```java
 class LanguageContext {
@@ -119,14 +128,14 @@ class LanguageContext {
     LanguageContext(Env env) {
         this.env = env;
     }
-    
+
     void ensureInitialized() {
         if (!initialized) {
             CompilerDirectives.transferToInterpreterAndInvalidate();
             initialize();
         }
     }
-    
+
     private void initialize() {
         // perform initialization
         initialized = true;
@@ -146,9 +155,8 @@ class LanguageContextDrivenInitialization extends RootNode {
 }
 ```
 
-If the `TruffleLanguage.Registration.contextPolicy` of `MyLanguage` is `SHARED`, a new language context is created for each polyglot context used to run the language code. Therefore,
-`languageContext` is not a PE constant and so the number of deoptimizations (and invalidations) driven by the
-`initialized` boolean is unbounded.
+If `TruffleLanguage.Registration.contextPolicy` of `MyLanguage` is `SHARED`, a new language context is created for each polyglot context used to run the language code.
+Therefore, `languageContext` is not a PE constant and so the number of deoptimizations (and invalidations) driven by the `initialized` boolean is unbounded.
 
 A possible solution for this problem would be to transfer to the interpreter only when `languageContext` is a PE constant, and to annotate the initialize method with `TruffleBoundary`:
 
@@ -232,10 +240,12 @@ class RootNode {
 
 The dispatch node has a single call site, and each uninitialized call target must be initialized before the call.
 Initialization is performed in the `getCallTarget` method if the compilation final field `callTarget` on the callee's `RootNode` object is `null`.
-The callee’s root node object is not a PE constant. In fact, the number of root nodes the compiled code can see is theoretically unbounded.
+The callee’s root node object is not a PE constant.
+In fact, the number of root nodes the compiled code can see is theoretically unbounded.
 Initializing a call target causes a deoptimization, so the entire pattern leads to a deoptimization cycle.
 
-A possible solution to this problem would be to initialize the call target at parse time or when the function is looked up for the first time. `MyFunction` objects would then store the call targets directly:
+A possible solution to this problem would be to initialize the call target at parse time or when the function is looked up for the first time.
+`MyFunction` objects would then store the call targets directly:
 
 ```java
 class MyFunction {
@@ -275,7 +285,8 @@ class SkippedExceptionNode extends RootNode {
 }
 ```
 
-Skipped exceptions are exceptions that always cause a deoptimization. The complete list is as follows:
+Skipped exceptions are exceptions that always cause a deoptimization.
+The complete list is as follows:
 * `UnexpectedResultException`
 * `SlowPathException`
 * `ScopedMemoryAccess$ScopedAccessError`
@@ -290,9 +301,9 @@ Skipped exceptions are exceptions that always cause a deoptimization. The comple
 * `ReadOnlyBufferException`
 * `AssertionError`
 
-As you can see from the example, catching the exception does not help. Whenever a skipped exception is thrown in Truffle-compiled code,
-the code is deoptimized and invalidated, and repeated execution of such code leads to a deoptimization cycle.
+As you can see from the example, catching the exception does not help.
+Whenever a skipped exception is thrown in Truffle-compiled code, the code is deoptimized and invalidated, and repeated execution of such code leads to a deoptimization cycle.
 
-The solution to this problem is to ensure that a skipped exception is never thrown from compiled code.
-This can be achieved either by throwing the exception behind a `TruffleBoundary` or ensuring, with explicit guards,
-that the error cannot occur in compiled code.
+The solution to this problem is to ensure that skipped exceptions are never thrown from compiled code. You can achieve this by either:
+* Throwing the exception behind `TruffleBoundary`, or
+* Using explicit guards to guarantee that the exception cannot be thrown in compiled code.