0
# Truffle Runtime
1

2
The Truffle Runtime is the core execution engine for dynamic programming languages built with the Truffle framework. It provides runtime support, compilation services, optimization infrastructure, and language interoperability capabilities. The runtime automatically compiles and optimizes Abstract Syntax Trees (ASTs) into high-performance native code through integration with the Graal compiler.
3

4
## Package Information
5

6
- **Package Name**: org.graalvm.truffle:truffle-runtime
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10
  ```xml
11
  <dependency>
12
    <groupId>org.graalvm.truffle</groupId>
13
    <artifactId>truffle-runtime</artifactId>
14
    <version>24.2.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.oracle.truffle.api.Truffle;
22
import com.oracle.truffle.api.TruffleRuntime;
23
import com.oracle.truffle.api.nodes.Node;
24
import com.oracle.truffle.api.nodes.RootNode;
25
import com.oracle.truffle.api.frame.VirtualFrame;
26
import com.oracle.truffle.api.frame.Frame;
27
import com.oracle.truffle.api.interop.InteropLibrary;
28
import com.oracle.truffle.api.TruffleLanguage;
29
```
30

31
Note: The runtime is typically accessed through the Truffle API rather than direct imports. Direct use of runtime classes is generally not recommended for language implementers.
32

33
## Basic Usage
34

35
```java
36
import com.oracle.truffle.api.Truffle;
37
import com.oracle.truffle.api.TruffleRuntime;
38
import com.oracle.truffle.api.nodes.RootNode;
39
import com.oracle.truffle.api.CallTarget;
40

41
// Access the runtime through the Truffle API
42
TruffleRuntime runtime = Truffle.getRuntime();
43

44
// Create a call target from a root node
45
RootNode rootNode = new MyLanguageRootNode();
46
CallTarget callTarget = runtime.createCallTarget(rootNode);
47

48
// The runtime automatically handles compilation and optimization
49
Object result = callTarget.call();
50
```
51

52
## Architecture
53

54
The Truffle Runtime is built around several key components:
55

56
- **Runtime Core**: Main execution engine and service provider framework
57
- **Compilation System**: Integration with Graal compiler for optimized code generation
58
- **Optimization Engine**: Assumptions, profiles, and adaptive compilation strategies
59
- **Monitoring System**: Java Flight Recorder integration and performance event tracking
60
- **Service Framework**: Extensible SPI system for custom runtime behaviors
61

62
## Capabilities
63

64
### Runtime Management
65

66
Core runtime services for accessing the execution engine, creating call targets, and managing runtime options.
67

68
```java { .api }
69
public abstract class TruffleRuntime {
70
    public abstract CallTarget createCallTarget(RootNode rootNode);
71
    public abstract String getName();
72
    public abstract void notifyTransferToInterpreter();
73
    public abstract boolean isProfilingEnabled();
74
}
75
```
76

77
[Runtime Management](./runtime-management.md)
78

79
### Node Framework
80

81
Abstract Syntax Tree (AST) node framework providing the foundation for building executable language interpreters with optimization support.
82

83
```java { .api }
84
public abstract class Node {
85
    public final Node getParent();
86
    public final <T extends Node> T replace(T newNode);
87
    public final RootNode getRootNode();
88
    public SourceSection getSourceSection();
89
}
90

91
public abstract class RootNode extends Node {
92
    public abstract Object execute(VirtualFrame frame);
93
    public final CallTarget getCallTarget();
94
}
95
```
96

97
[Node Framework](./nodes.md)
98

99
### Frame Management
100

101
Execution frame system providing efficient storage and access to method arguments, local variables, and temporary values.
102

103
```java { .api }
104
public interface VirtualFrame extends Frame {
105
    Object[] getArguments();
106
    MaterializedFrame materialize();
107
    Object getObject(FrameSlot slot) throws FrameSlotTypeException;
108
    void setObject(FrameSlot slot, Object value);
109
    int getInt(FrameSlot slot) throws FrameSlotTypeException;
110
    void setInt(FrameSlot slot, int value);
111
}
112
```
113

114
[Frame Management](./frames.md)
115

116
### Language Implementation SPI
117

118
Service Provider Interface (SPI) for implementing programming languages on the Truffle framework.
119

120
```java { .api }
121
public abstract class TruffleLanguage<C> {
122
    protected abstract C createContext(Env env);
123
    protected abstract CallTarget parse(ParsingRequest request) throws Exception;
124
    protected Object findMetaObject(C context, Object value);
125
}
126

127
@Registration(id = "mylang", name = "My Language", version = "1.0")
128
public class MyLanguage extends TruffleLanguage<MyLanguageContext> {
129
    // Implementation
130
}
131
```
132

133
[Language Implementation SPI](./language-spi.md)
134

135
### Interoperability
136

137
Language interoperability framework enabling seamless interaction between different programming languages through the InteropLibrary protocol.
138

139
```java { .api }
140
public abstract class InteropLibrary extends Library {
141
    public boolean isNull(Object receiver);
142
    public boolean isExecutable(Object receiver);
143
    public Object execute(Object receiver, Object... arguments);
144
    public boolean hasMembers(Object receiver);
145
    public Object readMember(Object receiver, String member);
146
    public void writeMember(Object receiver, String member, Object value);
147
}
148
```
149

150
[Interoperability](./interoperability.md)
151

152
### Compilation and Optimization
153

154
Compilation infrastructure providing optimized call targets, compiler directives, and assumption-based optimizations.
155

156
```java { .api }
157
public abstract class OptimizedCallTarget implements CallTarget {
158
    public abstract boolean isValid();
159
    public abstract void invalidate();
160
    public abstract int getCallCount();
161
    public abstract long getCompilationTime();
162
    public abstract boolean isCompiling();
163
}
164

165
public final class CompilerDirectives {
166
    public static void transferToInterpreter();
167
    public static void transferToInterpreterAndInvalidate();
168
    public static boolean inInterpreter();
169
    public static boolean inCompiledCode();
170
    public static boolean isCompilationConstant(Object value);
171
}
172
```
173

174
[Compilation and Optimization](./compilation-optimization.md)
175

176
### Service Provider Framework
177

178
Extensible SPI system allowing customization of runtime behaviors including loop node creation, engine caching, and type system integration.
179

180
```java { .api }
181
public interface LoopNodeFactory {
182
    LoopNode createLoopNode(RepeatingNode repeatingNode);
183
}
184

185
public interface EngineCacheSupport {
186
    <T> T getEngineCache(Object key, Supplier<T> valueSupplier);
187
    void clearEngineCache();
188
}
189

190
public interface TruffleTypes {
191
    Class<?> getJavaClass(Object value);
192
    String getJavaClassName(Object value);
193
}
194
```
195

196
[Service Provider Framework](./service-provider-framework.md)
197

198
### Monitoring and Profiling
199

200
Comprehensive monitoring capabilities including Java Flight Recorder integration, performance event tracking, and runtime listeners.
201

202
```java { .api }
203
public interface GraalTruffleRuntimeListener {
204
    void onCompilationQueued(OptimizedCallTarget callTarget);
205
    void onCompilationStarted(OptimizedCallTarget callTarget);
206
    void onCompilationTruffleTierFinished(OptimizedCallTarget callTarget, TruffleTierContext context, GraphInfo graph);
207
    void onCompilationGraalTierFinished(OptimizedCallTarget callTarget, GraphInfo graph);
208
    void onCompilationSuccess(OptimizedCallTarget callTarget, TruffleTierContext context, GraphInfo graph, CompilationResultInfo info, int tier);
209
    void onCompilationFailed(OptimizedCallTarget callTarget, String reason, boolean bailout, boolean permanentBailout, int tier);
210
}
211
```
212

213
[Monitoring and Profiling](./monitoring-profiling.md)
214

215
## Common Types
216

217
```java { .api }
218
public abstract class CallTarget {
219
    public abstract Object call(Object... arguments);
220
}
221

222
public abstract class RootNode extends Node {
223
    public abstract Object execute(VirtualFrame frame);
224
    public CallTarget getCallTarget();
225
}
226

227
public interface VirtualFrame extends Frame {
228
    Object[] getArguments();
229
    MaterializedFrame materialize();
230
}
231

232
public interface MaterializedFrame extends Frame {
233
    // Persistent frame that can exist beyond call stack
234
}
235

236
public interface Frame {
237
    FrameDescriptor getFrameDescriptor();
238
    Object[] getArguments();
239
    Object getObject(FrameSlot slot) throws FrameSlotTypeException;
240
    void setObject(FrameSlot slot, Object value);
241
}
242

243
public abstract class FrameDescriptor {
244
    public static FrameDescriptor create();
245
    public abstract FrameSlot addFrameSlot(Object identifier);
246
    public abstract FrameSlot findFrameSlot(Object identifier);
247
}
248

249
public abstract class FrameSlot {
250
    public abstract Object getIdentifier();
251
    public abstract int getIndex();
252
}
253

254
public final class FrameSlotTypeException extends SlowPathException {
255
    // Exception for wrong slot type access
256
}
257

258
public interface LoopNode {
259
    void execute(VirtualFrame frame);
260
    RepeatingNode getRepeatingNode();
261
}
262

263
public interface RepeatingNode {
264
    boolean executeRepeating(VirtualFrame frame);
265
}
266

267
public interface Library {
268
    boolean accepts(Object receiver);
269
}
270

271
public enum CompilationFailureAction {
272
    Silent,
273
    Print,
274
    Throw,
275
    ExitVM,
276
    Diagnose
277
}
278

279
public final class SourceSection {
280
    public Source getSource();
281
    public int getStartLine();
282
    public int getStartColumn();
283
    public CharSequence getCharacters();
284
}
285
```