0
# Runtime Management
1

2
Core runtime services for accessing the execution engine, creating call targets, and managing runtime configuration options.
3

4
## Capabilities
5

6
### TruffleRuntime
7

8
The main interface for accessing runtime services and creating optimized call targets.
9

10
```java { .api }
11
/**
12
 * Main interface for accessing Truffle runtime services
13
 * Obtained via Truffle.getRuntime()
14
 */
15
public abstract class TruffleRuntime {
16
    /** Creates an optimized call target from a root node */
17
    public abstract CallTarget createCallTarget(RootNode rootNode);
18
    
19
    /** Returns the name of this runtime implementation */
20
    public abstract String getName();
21
    
22
    /** Notifies the runtime of transfer from compiled to interpreted code */
23
    public abstract void notifyTransferToInterpreter();
24
    
25
    /** Checks if profiling is currently enabled */
26
    public abstract boolean isProfilingEnabled();
27
    
28
    /** Creates a new virtual frame for method execution */
29
    public abstract VirtualFrame createVirtualFrame(Object[] arguments, FrameDescriptor frameDescriptor);
30
    
31
    /** Creates a new materialized frame from arguments */
32
    public abstract MaterializedFrame createMaterializedFrame(Object[] arguments, FrameDescriptor frameDescriptor);
33
    
34
    /** Creates a new materialized frame from an existing virtual frame */
35
    public abstract MaterializedFrame createMaterializedFrame(Object[] arguments);
36
    
37
    /** Returns the frame instance currently on the stack */
38
    public abstract FrameInstance getCurrentFrame();
39
    
40
    /** Returns an iterable of all frames currently on the stack */
41
    public abstract Iterable<FrameInstance> getStackTrace();
42
    
43
    /** Creates a new assumption for optimization purposes */
44
    public abstract Assumption createAssumption();
45
    
46
    /** Creates a new assumption with a name for optimization purposes */
47
    public abstract Assumption createAssumption(String name);
48
}
49
```
50

51
**Usage Examples:**
52

53
```java
54
import com.oracle.truffle.api.Truffle;
55
import com.oracle.truffle.api.TruffleRuntime;
56
import com.oracle.truffle.api.nodes.RootNode;
57
import com.oracle.truffle.api.CallTarget;
58
import com.oracle.truffle.api.Assumption;
59

60
// Get the runtime instance
61
TruffleRuntime runtime = Truffle.getRuntime();
62

63
// Create a call target
64
RootNode rootNode = new MyLanguageRootNode();
65
CallTarget callTarget = runtime.createCallTarget(rootNode);
66

67
// Check runtime capabilities
68
if (runtime.isProfilingEnabled()) {
69
    System.out.println("Profiling is enabled");
70
}
71

72
// Create assumptions for optimization
73
Assumption validAssumption = runtime.createAssumption("MyOptimization");
74
```
75

76
### AbstractTruffleRuntime
77

78
Base implementation providing common runtime functionality.
79

80
```java { .api }
81
/**
82
 * Abstract base class for Truffle runtime implementations
83
 */
84
public abstract class AbstractTruffleRuntime extends TruffleRuntime {
85
    /** Returns the default call target for root nodes */
86
    public CallTarget createCallTarget(RootNode rootNode) {
87
        return createCallTarget(rootNode, CallTarget.class);
88
    }
89
    
90
    /** Creates a call target with specific target class */
91
    public abstract <T extends CallTarget> T createCallTarget(RootNode rootNode, Class<T> clazz);
92
}
93
```
94

95
### GraalTruffleRuntime
96

97
Main implementation of the Truffle runtime using Graal compiler integration.
98

99
```java { .api }
100
/**
101
 * Graal-based implementation of the Truffle runtime
102
 * Provides optimizing compilation and advanced runtime features
103
 */
104
public final class GraalTruffleRuntime extends OptimizedTruffleRuntime {
105
    /** Returns the singleton instance of the Graal Truffle runtime */
106
    public static GraalTruffleRuntime getRuntime();
107
    
108
    /** Returns the runtime name */
109
    public String getName();
110
    
111
    /** Adds a listener for runtime events */
112
    public void addListener(GraalTruffleRuntimeListener listener);
113
    
114
    /** Removes a runtime event listener */
115
    public void removeListener(GraalTruffleRuntimeListener listener);
116
    
117
    /** Returns statistics about compilation performance */
118
    public CompilerOptions getCompilerOptions();
119
    
120
    /** Forces garbage collection of optimized code */
121
    public void clearCachedCallTargets();
122
}
123
```
124

125
### Runtime Options
126

127
Configuration options for controlling runtime behavior.
128

129
```java { .api }
130
/**
131
 * Configuration options for the Truffle runtime
132
 */
133
public final class TruffleRuntimeOptions {
134
    /** Maximum number of calls before compilation triggers */
135
    public static final OptionKey<Integer> COMPILATION_CALL_THRESHOLD = new OptionKey<>(1000);
136
    
137
    /** Maximum number of loop iterations before OSR compilation */
138
    public static final OptionKey<Integer> OSR_COMPILATION_THRESHOLD = new OptionKey<>(100000);
139
    
140
    /** Whether to enable compilation statistics */
141
    public static final OptionKey<Boolean> COMPILATION_STATISTICS = new OptionKey<>(false);
142
    
143
    /** Whether to trace compilation events */
144
    public static final OptionKey<Boolean> TRACE_COMPILATION = new OptionKey<>(false);
145
    
146
    /** Action to take when compilation fails */
147
    public static final OptionKey<CompilationFailureAction> COMPILATION_FAILURE_ACTION = 
148
        new OptionKey<>(CompilationFailureAction.Silent);
149
}
150

151
public final class OptimizedRuntimeOptions {
152
    /** Enable background compilation */
153
    public static final OptionKey<Boolean> BACKGROUND_COMPILATION = new OptionKey<>(true);
154
    
155
    /** Number of compiler threads to use */
156
    public static final OptionKey<Integer> COMPILER_THREADS = new OptionKey<>(2);
157
    
158
    /** Whether to enable splitting optimization */
159
    public static final OptionKey<Boolean> SPLITTING = new OptionKey<>(true);
160
    
161
    /** Whether to enable OSR (On Stack Replacement) */
162
    public static final OptionKey<Boolean> OSR = new OptionKey<>(true);
163
}
164
```
165

166
**Usage Examples:**
167

168
```java
169
// Access runtime options through the engine
170
Context context = Context.newBuilder()
171
    .option("engine.CompilationCallThreshold", "500")
172
    .option("engine.BackgroundCompilation", "false")
173
    .build();
174

175
// Runtime automatically applies these settings
176
TruffleRuntime runtime = Truffle.getRuntime();
177
```
178

179
## Common Types
180

181
```java { .api }
182
public interface FrameInstance {
183
    /** Returns the frame at this stack position */
184
    Frame getFrame(FrameAccess access);
185
    
186
    /** Returns the call node that created this frame */
187
    Node getCallNode();
188
    
189
    /** Returns the call target for this frame */
190
    CallTarget getCallTarget();
191
    
192
    /** Checks if this is a virtual frame */
193
    boolean isVirtualFrame();
194
}
195

196
public enum FrameAccess {
197
    /** No frame access required */
198
    NONE,
199
    /** Read-only access to frame */
200
    READ_ONLY,  
201
    /** Read-write access to frame */
202
    READ_WRITE,
203
    /** Materialize the frame */
204
    MATERIALIZE
205
}
206

207
public abstract class FrameDescriptor {
208
    /** Creates a new frame descriptor */
209
    public static FrameDescriptor create();
210
    
211
    /** Creates a new frame descriptor with default value */
212
    public static FrameDescriptor create(Object defaultValue);
213
    
214
    /** Adds a new frame slot */
215
    public abstract FrameSlot addFrameSlot(Object identifier);
216
    
217
    /** Finds an existing frame slot by identifier */
218
    public abstract FrameSlot findFrameSlot(Object identifier);
219
    
220
    /** Returns all frame slots */
221
    public abstract List<? extends FrameSlot> getSlots();
222
}
223
```