0
# Frame Management
1

2
Execution frame system providing efficient storage and access to method arguments, local variables, and temporary values during AST interpretation.
3

4
## Capabilities
5

6
### Frame
7

8
Base interface for accessing execution context including arguments and local variables.
9

10
```java { .api }
11
/**
12
 * Base interface for execution frames containing arguments and local variables
13
 * Provides access to the execution context of a method or function
14
 */
15
public interface Frame {
16
    /** Returns the frame descriptor defining the frame layout */
17
    FrameDescriptor getFrameDescriptor();
18
    
19
    /** Returns the arguments passed to this frame */
20
    Object[] getArguments();
21
    
22
    /** Materializes this frame for persistence beyond the call stack */
23
    MaterializedFrame materialize();
24
    
25
    // === Object Slot Access ===
26
    
27
    /** Gets the value from an object slot */
28
    Object getObject(FrameSlot slot) throws FrameSlotTypeException;
29
    
30
    /** Sets the value in an object slot */
31
    void setObject(FrameSlot slot, Object value);
32
    
33
    /** Gets object value by identifier */
34
    Object getObject(Object identifier) throws FrameSlotTypeException;
35
    
36
    /** Sets object value by identifier */
37
    void setObject(Object identifier, Object value);
38
    
39
    // === Primitive Slot Access ===
40
    
41
    /** Gets a byte value from a slot */
42
    byte getByte(FrameSlot slot) throws FrameSlotTypeException;
43
    
44
    /** Sets a byte value in a slot */
45
    void setByte(FrameSlot slot, byte value);
46
    
47
    /** Gets an int value from a slot */
48
    int getInt(FrameSlot slot) throws FrameSlotTypeException;
49
    
50
    /** Sets an int value in a slot */
51
    void setInt(FrameSlot slot, int value);
52
    
53
    /** Gets a long value from a slot */
54
    long getLong(FrameSlot slot) throws FrameSlotTypeException;
55
    
56
    /** Sets a long value in a slot */
57
    void setLong(FrameSlot slot, long value);
58
    
59
    /** Gets a float value from a slot */
60
    float getFloat(FrameSlot slot) throws FrameSlotTypeException;
61
    
62
    /** Sets a float value in a slot */
63
    void setFloat(FrameSlot slot, float value);
64
    
65
    /** Gets a double value from a slot */
66
    double getDouble(FrameSlot slot) throws FrameSlotTypeException;
67
    
68
    /** Sets a double value in a slot */
69
    void setDouble(FrameSlot slot, double value);
70
    
71
    /** Gets a boolean value from a slot */
72
    boolean getBoolean(FrameSlot slot) throws FrameSlotTypeException;
73
    
74
    /** Sets a boolean value in a slot */
75
    void setBoolean(FrameSlot slot, boolean value);
76
    
77
    // === Auxiliary Slot Access ===
78
    
79
    /** Gets auxiliary data from a slot */
80
    Object getAuxiliarySlot(FrameSlot slot);
81
    
82
    /** Sets auxiliary data in a slot */
83
    void setAuxiliarySlot(FrameSlot slot, Object value);
84
    
85
    // === Slot Management ===
86
    
87
    /** Checks if a slot is of object type */
88
    boolean isObject(FrameSlot slot);
89
    
90
    /** Checks if a slot is of byte type */
91
    boolean isByte(FrameSlot slot);
92
    
93
    /** Checks if a slot is of int type */
94
    boolean isInt(FrameSlot slot);
95
    
96
    /** Checks if a slot is of long type */
97
    boolean isLong(FrameSlot slot);
98
    
99
    /** Checks if a slot is of float type */
100
    boolean isFloat(FrameSlot slot);
101
    
102
    /** Checks if a slot is of double type */
103
    boolean isDouble(FrameSlot slot);
104
    
105
    /** Checks if a slot is of boolean type */
106
    boolean isBoolean(FrameSlot slot);
107
    
108
    /** Gets the value from a slot without type checking */
109
    Object getValue(FrameSlot slot);
110
    
111
    /** Clears the value in a slot */
112
    void clear(FrameSlot slot);
113
}
114
```
115

116
### VirtualFrame
117

118
Optimized frame implementation for efficient execution on the call stack.
119

120
```java { .api }
121
/**
122
 * Optimized frame for efficient execution
123
 * Lives on the call stack and provides fast access to frame data
124
 */
125
public interface VirtualFrame extends Frame {
126
    /** 
127
     * Materializes this virtual frame into a persistent materialized frame
128
     * The materialized frame can be stored beyond the current call
129
     */
130
    MaterializedFrame materialize();
131
    
132
    /**
133
     * Checks if this frame has been materialized
134
     * Materialization affects performance characteristics
135
     */
136
    boolean isMaterialized();
137
}
138
```
139

140
### MaterializedFrame
141

142
Persistent frame that can be stored and accessed beyond the current call stack.
143

144
```java { .api }
145
/**
146
 * Persistent frame that can exist beyond the call stack
147
 * Used for closures, continuations, and debugging
148
 */
149
public interface MaterializedFrame extends Frame {
150
    // Inherits all Frame methods
151
    // No additional methods - marker interface for persistent frames
152
}
153
```
154

155
### FrameDescriptor
156

157
Template defining the layout and structure of frames, including slot definitions and metadata.
158

159
```java { .api }
160
/**
161
 * Descriptor defining the structure and layout of execution frames
162
 * Specifies available slots and their properties
163
 */
164
public abstract class FrameDescriptor implements Cloneable {
165
    /** Creates a new frame descriptor */
166
    public static FrameDescriptor create();
167
    
168
    /** Creates a frame descriptor with a default value */
169
    public static FrameDescriptor create(Object defaultValue);
170
    
171
    /** Adds a new frame slot with the given identifier */
172
    public abstract FrameSlot addFrameSlot(Object identifier);
173
    
174
    /** Adds a new frame slot with identifier and kind */
175
    public abstract FrameSlot addFrameSlot(Object identifier, FrameSlotKind kind);
176
    
177
    /** Adds a new frame slot with identifier, info, and kind */
178
    public abstract FrameSlot addFrameSlot(Object identifier, Object info, FrameSlotKind kind);
179
    
180
    /** Finds a frame slot by identifier */
181
    public abstract FrameSlot findFrameSlot(Object identifier);
182
    
183
    /** Finds or adds a frame slot */
184
    public abstract FrameSlot findOrAddFrameSlot(Object identifier);
185
    
186
    /** Finds or adds a frame slot with kind */
187
    public abstract FrameSlot findOrAddFrameSlot(Object identifier, FrameSlotKind kind);
188
    
189
    /** Finds or adds a frame slot with info and kind */
190
    public abstract FrameSlot findOrAddFrameSlot(Object identifier, Object info, FrameSlotKind kind);
191
    
192
    /** Returns all frame slots */
193
    public abstract List<? extends FrameSlot> getSlots();
194
    
195
    /** Returns the number of slots */
196
    public abstract int getSize();
197
    
198
    /** Returns the default value for uninitialized slots */
199
    public abstract Object getDefaultValue();
200
    
201
    /** Creates a shallow copy of this descriptor */
202
    public abstract FrameDescriptor shallowCopy();
203
    
204
    /** Creates a deep copy of this descriptor */
205
    public FrameDescriptor copy();
206
}
207
```
208

209
### FrameSlot
210

211
Individual slot within a frame for storing local variables and temporary values.
212

213
```java { .api }
214
/**
215
 * Individual slot within a frame for storing values
216
 * Represents a local variable or temporary storage location
217
 */
218
public abstract class FrameSlot implements Cloneable {
219
    /** Returns the slot identifier */
220
    public abstract Object getIdentifier();
221
    
222
    /** Returns additional slot information */
223
    public abstract Object getInfo();
224
    
225
    /** Sets additional slot information */
226
    public abstract void setInfo(Object info);
227
    
228
    /** Returns the slot kind (optimization hint) */
229
    public abstract FrameSlotKind getKind();
230
    
231
    /** Sets the slot kind */
232
    public abstract void setKind(FrameSlotKind kind);
233
    
234
    /** Returns the slot index in the frame */
235
    public abstract int getIndex();
236
    
237
    /** Checks if this slot equals another slot */
238
    public final boolean equals(Object obj);
239
    
240
    /** Returns hash code for this slot */
241
    public final int hashCode();
242
    
243
    /** Returns string representation */
244
    public final String toString();
245
}
246
```
247

248
### FrameSlotKind
249

250
Type hint enumeration for optimizing frame slot storage.
251

252
```java { .api }
253
/**
254
 * Type hint for frame slots to enable storage optimizations
255
 */
256
public enum FrameSlotKind {
257
    /** Object reference storage */
258
    Object,
259
    
260
    /** Long integer storage */
261
    Long,
262
    
263
    /** Integer storage */
264
    Int,
265
    
266
    /** Double precision floating point storage */
267
    Double,
268
    
269
    /** Single precision floating point storage */
270
    Float,
271
    
272
    /** Boolean storage */
273
    Boolean,
274
    
275
    /** Byte storage */
276
    Byte,
277
    
278
    /** Illegal/uninitialized storage */
279
    Illegal;
280
    
281
    /** Tag value for this kind */
282
    public final byte tag;
283
}
284
```
285

286
### Frame Utilities and Exceptions
287

288
Utilities for working with frames and handling frame-related errors.
289

290
```java { .api }
291
/**
292
 * Exception thrown when accessing a frame slot with wrong type
293
 */
294
public final class FrameSlotTypeException extends SlowPathException {
295
    /** Creates exception for wrong slot type access */
296
    public FrameSlotTypeException();
297
    
298
    /** Creates exception with custom message */
299
    public FrameSlotTypeException(String message);
300
}
301

302
/**
303
 * Utility methods for working with frames
304
 */
305
public final class FrameUtil {
306
    /** Gets object value with type checking */
307
    public static Object getObjectSafe(Frame frame, FrameSlot slot);
308
    
309
    /** Gets int value with type checking */
310
    public static int getIntSafe(Frame frame, FrameSlot slot);
311
    
312
    /** Gets long value with type checking */
313
    public static long getLongSafe(Frame frame, FrameSlot slot);
314
    
315
    /** Gets double value with type checking */
316
    public static double getDoubleSafe(Frame frame, FrameSlot slot);
317
    
318
    /** Gets float value with type checking */
319
    public static float getFloatSafe(Frame frame, FrameSlot slot);
320
    
321
    /** Gets boolean value with type checking */
322
    public static boolean getBooleanSafe(Frame frame, FrameSlot slot);
323
    
324
    /** Gets byte value with type checking */
325
    public static byte getByteSafe(Frame frame, FrameSlot slot);
326
}
327
```
328

329
**Usage Examples:**
330

331
```java
332
import com.oracle.truffle.api.frame.*;
333

334
public class MyLanguageLocalVariableNode extends MyLanguageExpressionNode {
335
    private final FrameSlot slot;
336
    
337
    public MyLanguageLocalVariableNode(FrameSlot slot) {
338
        this.slot = slot;
339
    }
340
    
341
    @Override
342
    public Object execute(VirtualFrame frame) {
343
        try {
344
            // Try to read as the expected type first
345
            if (frame.isInt(slot)) {
346
                return frame.getInt(slot);
347
            } else if (frame.isDouble(slot)) {
348
                return frame.getDouble(slot);
349
            } else if (frame.isBoolean(slot)) {
350
                return frame.getBoolean(slot);
351
            } else {
352
                return frame.getObject(slot);
353
            }
354
        } catch (FrameSlotTypeException e) {
355
            // Fall back to object access
356
            return frame.getValue(slot);
357
        }
358
    }
359
}
360

361
public class MyLanguageAssignmentNode extends MyLanguageStatementNode {
362
    @Child private MyLanguageExpressionNode valueNode;
363
    private final FrameSlot slot;
364
    
365
    public MyLanguageAssignmentNode(FrameSlot slot, MyLanguageExpressionNode valueNode) {
366
        this.slot = slot;
367
        this.valueNode = valueNode;
368
    }
369
    
370
    @Override
371
    public Object execute(VirtualFrame frame) {
372
        Object value = valueNode.execute(frame);
373
        
374
        // Optimize storage based on value type
375
        if (value instanceof Integer) {
376
            slot.setKind(FrameSlotKind.Int);
377
            frame.setInt(slot, (Integer) value);
378
        } else if (value instanceof Double) {
379
            slot.setKind(FrameSlotKind.Double);
380
            frame.setDouble(slot, (Double) value);
381
        } else if (value instanceof Boolean) {
382
            slot.setKind(FrameSlotKind.Boolean);
383
            frame.setBoolean(slot, (Boolean) value);
384
        } else {
385
            slot.setKind(FrameSlotKind.Object);
386
            frame.setObject(slot, value);
387
        }
388
        
389
        return value;
390
    }
391
}
392

393
// Creating a frame descriptor for a function
394
public class MyLanguageFunctionParser {
395
    public RootNode parseFunction(String name, List<String> parameters, Node body) {
396
        FrameDescriptor.Builder builder = FrameDescriptor.newBuilder();
397
        
398
        // Add slots for parameters
399
        List<FrameSlot> parameterSlots = new ArrayList<>();
400
        for (String param : parameters) {
401
            FrameSlot slot = builder.addSlot(FrameSlotKind.Illegal, param, null);
402
            parameterSlots.add(slot);
403
        }
404
        
405
        FrameDescriptor frameDescriptor = builder.build();
406
        
407
        return new MyLanguageFunctionRootNode(
408
            getCurrentLanguageInfo(),
409
            frameDescriptor,
410
            body,
411
            name,
412
            parameterSlots
413
        );
414
    }
415
}
416
```
417

418
## Common Types
419

420
```java { .api }
421
public abstract class SlowPathException extends Exception {
422
    /** Base class for exceptions that should not affect compilation */
423
    protected SlowPathException() {
424
        super();
425
    }
426
    
427
    protected SlowPathException(String message) {
428
        super(message);
429
    }
430
}
431

432
public final class FrameDescriptor.Builder {
433
    /** Builder for creating frame descriptors */
434
    
435
    /** Adds a slot with the given kind and identifier */
436
    public FrameSlot addSlot(FrameSlotKind kind, Object identifier, Object info);
437
    
438
    /** Builds the frame descriptor */
439
    public FrameDescriptor build();
440
}
441
```