diff --git a/truffle/docs/AuxiliaryEngineCachingEnterprise.md b/truffle/docs/AuxiliaryEngineCachingEnterprise.md index fc1e709deae4..43c93e1e4eeb 100644 --- a/truffle/docs/AuxiliaryEngineCachingEnterprise.md +++ b/truffle/docs/AuxiliaryEngineCachingEnterprise.md @@ -19,7 +19,7 @@ This includes: 2. Execution and profiling of the guest application in the interpreter. 3. Compilation of the AST to machine code. -Within a single OS process, the work performed during warmup can be shared by specifying an [explicit engine](https://www.graalvm.org/reference-manual/embed-languages/#code-caching-across-multiple-contexts). +Within a single OS process, the work performed during warmup can be shared by specifying an [explicit engine](../../reference-manual/embedding/embed-languages.md/#code-caching-across-multiple-contexts). This requires language implementations to disable context-related optimizations to avoid deoptimizations between contexts that share code. Auxiliary engine caching builds upon the mechanism for disabling context-related optimizations and adds the capability to persist an engine with ASTs and optimized machine code to disk. This way, the work performed during warmup can be significantly reduced in the first application context of a new process. diff --git a/truffle/docs/DynamicObjectModel.md b/truffle/docs/DynamicObjectModel.md index f922cbaa220b..ad63e1ae0606 100644 --- a/truffle/docs/DynamicObjectModel.md +++ b/truffle/docs/DynamicObjectModel.md @@ -184,4 +184,4 @@ public abstract class MakePairNode extends BinaryExpressionNode { A high-level description of the object model has been published in [**An Object Storage Model for the Truffle Language Implementation Framework**](http://dl.acm.org/citation.cfm?id=2647517). -See [Truffle documentation](https://github.com/oracle/graal/tree/master/truffle/docs) and [publications](https://github.com/oracle/graal/blob/master/docs/Publications.md) for more tutorials, presentations, and publications about Truffle and GraalVM. +See [Truffle publications](https://github.com/oracle/graal/blob/master/docs/Publications.md) for more presentations and publications about Truffle and GraalVM. diff --git a/truffle/docs/InteropMigration.md b/truffle/docs/InteropMigration.md index 7baf9f706f45..f311f74db028 100644 --- a/truffle/docs/InteropMigration.md +++ b/truffle/docs/InteropMigration.md @@ -7,7 +7,7 @@ permalink: /graalvm-as-a-platform/language-implementation-framework/InteropMigra # Truffle Interop 2.0 This document is targeted at guest language and tool implementers. -It is recommended to read the [Truffle Library Tutorial](https://github.com/oracle/graal/blob/master/truffle/docs/TruffleLibraries.md) first, before proceeding. +It is recommended to read the [Truffle Library Tutorial](./TruffleLibraries.md) first, before proceeding. ## Motivation diff --git a/truffle/docs/LanguageTutorial.md b/truffle/docs/LanguageTutorial.md index f64a1570b074..2e14b4324c5b 100644 --- a/truffle/docs/LanguageTutorial.md +++ b/truffle/docs/LanguageTutorial.md @@ -19,5 +19,5 @@ Conference on Programming Language Design and Implementation [PLDI 2016](http:// Next Steps: * Start to subclass [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) for your own language implementation. * Fork [SimpleLanguage](https://github.com/graalvm/simplelanguage), a toy language that demonstrates how to use many Truffle features. -* Embed Truffle languages in Java host applications using the [Polyglot API](https://graalvm.org/reference-manual/embed-languages/). +* Embed Truffle languages in Java host applications using the [Polyglot API](../../reference-manual/embedding/embed-languages.md). * Read [GraalVM/Truffle publications](https://github.com/oracle/graal/blob/master/docs/Publications.md). diff --git a/truffle/docs/OnStackReplacement.md b/truffle/docs/OnStackReplacement.md index 722bf2df0161..7645ae9f6ef2 100644 --- a/truffle/docs/OnStackReplacement.md +++ b/truffle/docs/OnStackReplacement.md @@ -1,7 +1,7 @@ --- layout: docs toc_group: truffle -link_title: On-Stack Replacement +link_title: On-Stack Replacement permalink: /graalvm-as-a-platform/language-implementation-framework/OnStackReplacement/ --- # On-Stack Replacement (OSR) @@ -15,7 +15,7 @@ On-stack replacement (OSR) is a technique used in Truffle to "break out" of the Truffle supports OSR for both AST interpreters (i.e., ASTs with `LoopNode`s) and bytecode interpreters (i.e., nodes with dispatch loops). In either case, Truffle uses heuristics to detect when a long-running loop is being interpreted and can perform OSR to speed up execution. -## OSR for AST interpreters +## OSR for AST interpreters Languages using standard Truffle APIs get OSR for free on Graal. The runtime tracks the number of times a `LoopNode` (created using `TruffleRuntime.createLoopNode(RepeatingNode)`) executes in the interpreter. @@ -33,9 +33,9 @@ A bytecode dispatch node typically looks something like the following: ```java class BytecodeDispatchNode extends Node { @CompilationFinal byte[] bytecode; - + ... - + @ExplodeLoop(kind = ExplodeLoop.LoopExplosionKind.MERGE_EXPLODE) Object execute(VirtualFrame frame) { int bci = 0; @@ -81,7 +81,7 @@ The example above can be refactored to support OSR as follows: class BytecodeDispatchNode extends Node implements BytecodeOSRNode { @CompilationFinal byte[] bytecode; @CompilationFinal private Object osrMetadata; - + ... Object execute(VirtualFrame frame) { @@ -176,4 +176,3 @@ For example, in the compilation log, a bytecode OSR entry may look something lik ``` See [Debugging](https://github.com/oracle/graal/blob/master/compiler/docs/Debugging.md) for more details on debugging Graal compilations. - diff --git a/truffle/docs/Optimizing.md b/truffle/docs/Optimizing.md index 1824da72f7aa..bb642996e41f 100644 --- a/truffle/docs/Optimizing.md +++ b/truffle/docs/Optimizing.md @@ -577,7 +577,7 @@ The `--engine.TraceCompilation` option also shows CallTarget invalidations with ## Ideal Graph Visualizer -The [Ideal Graph Visualizer (IGV)](https://docs.oracle.com/en/graalvm/enterprise/21/docs/tools/igv/) is a tool to understand Truffle ASTs and the GraalVM compiler graphs. +The [Ideal Graph Visualizer (IGV)](../../tools/ideal-graph-visualizer.md) is a tool to understand Truffle ASTs and the GraalVM compiler graphs. A typical usage is to run with `--vm.Dgraal.Dump=Truffle:1 --vm.Dgraal.PrintGraph=Network`, which will show you Truffle ASTs, guest-language call graphs, and the Graal graphs as they leave the Truffle phase. If the `-Dgraal.PrintGraph=Network` flag is omitted then the dump files are placed in the `graal_dumps` directory, which you should then open in IGV. diff --git a/truffle/docs/Profiling.md b/truffle/docs/Profiling.md index 1435783b2144..e09e1701786a 100644 --- a/truffle/docs/Profiling.md +++ b/truffle/docs/Profiling.md @@ -9,7 +9,7 @@ permalink: /graalvm-as-a-platform/language-implementation-framework/Profiling/ There is no shortage of tools for profiling interpreters written using Truffle. When running in JVM mode you can use standard JVM tooling such as VisualVM, Java Flight Recorder, and Oracle Developer Studio. When running in Native Image you can use `callgrind` from the Valgrind tool suite, and other system tools such as `strace`. As a language running on GraalVM, other GraalVM tools can be used. -For a broad enough definition of profiling, you can also use the [Ideal Graph Visualizer (IGV)](https://docs.oracle.com/en/graalvm/enterprise/21/docs/tools/igv/) and C1 Visualizer to inspect the compiler output. +For a broad enough definition of profiling, you can also use the [Ideal Graph Visualizer (IGV)](../../tools/ideal-graph-visualizer.md) and C1 Visualizer to inspect the compiler output. This guide is less about how to use each tool and more about suggestions for extracting the most useful information from the tools, assuming a basic knowledge of their usage. diff --git a/truffle/docs/README.md b/truffle/docs/README.md index cb063485ac24..8e6ffe01268d 100644 --- a/truffle/docs/README.md +++ b/truffle/docs/README.md @@ -50,7 +50,7 @@ Consider reading [these publications](https://github.com/oracle/graal/blob/maste Implementing a language using Truffle offers a way to interoperate with other "Truffle" languages. To learn more about verifying that your language is a valid polyglot citizen, read more about using the [Polyglot TCK](./TCK.md). Somewhat related topics worth exploring are [Truffle Libraries](./TruffleLibraries.md), as well as how to use them to implement a language [interoperability](./InteropMigration.md). -Languages implemented with Truffle can also be embedded in Java host applications using the [Polyglot API](https://graalvm.org/reference-manual/embed-languages/). +Languages implemented with Truffle can also be embedded in Java host applications using the [Polyglot API](../../reference-manual/embedding/embed-languages.md). To better understand how to improve the performance of your language please consult the documentation on [profiling](./Profiling.md) and [optimizing](./Optimizing.md) your language. Also, to better understand how to use Truffle's automated monomorphization feature (i.e., splitting), look at the [related documentation](./splitting/Monomorphization.md). diff --git a/truffle/docs/StaticObjectModel.md b/truffle/docs/StaticObjectModel.md index b19c4041b12e..d09d5454713f 100644 --- a/truffle/docs/StaticObjectModel.md +++ b/truffle/docs/StaticObjectModel.md @@ -222,7 +222,7 @@ public void wrongShape(TruffleLanguage language) { ``` While these checks are often useful, they might be redundant if the language implementation already performs them, for example using a verifier. -While the first type of checks (on property type) is very efficient and cannot be disabled, the second type of checks (on the shape) is computationally expensive and can be disabled via a command line argument: +While the first type of checks (on property type) is very efficient and cannot be disabled, the second type of checks (on the shape) is computationally expensive and can be disabled via a command line argument: ``` --experimental-options --engine.RelaxStaticObjectSafetyChecks=true ```