0
# Domain-Specific Language (DSL)
1

2
The Truffle DSL provides annotation-driven code generation for creating optimized AST nodes with automatic specialization, caching, and fallback handling. It enables high-performance language implementations through compile-time optimization and runtime adaptation.
3

4
## Capabilities
5

6
### Node Specialization System
7

8
Core specialization system allowing nodes to optimize for specific types and conditions through generated code.
9

10
```java { .api }
11
/**
12
 * Marks a method as a specialization of a node operation
13
 */
14
@Retention(RetentionPolicy.CLASS)
15
@Target(ElementType.METHOD)
16
public @interface Specialization {
17
    
18
    /**
19
     * Guards that must be true for this specialization
20
     * @return Array of guard expressions
21
     */
22
    String[] guards() default {};
23
    
24
    /**
25
     * Assumptions that must be valid for this specialization
26
     * @return Array of assumption expressions
27
     */
28
    String[] assumptions() default {};
29
    
30
    /**
31
     * Limit for polymorphic inline caching
32
     * @return Maximum number of cached instances
33
     */
34
    String limit() default "";
35
    
36
    /**
37
     * Conditions for rewriting to this specialization
38
     * @return Array of condition expressions
39
     */
40
    String[] replaces() default {};
41
    
42
    /**
43
     * Whether this specialization contains a slow path
44
     * @return true if contains slow path
45
     */
46
    boolean insertBefore() default false;
47
}
48

49
/**
50
 * Marks a fallback method for handling uncovered cases
51
 */
52
@Retention(RetentionPolicy.CLASS)
53
@Target(ElementType.METHOD)
54
public @interface Fallback {
55
}
56

57
/**
58
 * Caches values for specializations
59
 */
60
@Retention(RetentionPolicy.CLASS)
61
@Target(ElementType.PARAMETER)
62
public @interface Cached {
63
    
64
    /**
65
     * Expression for computing cached value
66
     * @return Cache expression
67
     */
68
    String value() default "";
69
    
70
    /**
71
     * Limit for cache size
72
     * @return Maximum cache entries
73
     */
74
    String limit() default "3";
75
    
76
    /**
77
     * Whether to use weak references
78
     * @return true for weak references
79
     */
80
    boolean weak() default false;
81
    
82
    /**
83
     * Dimensions for multidimensional caching
84
     * @return Cache dimensions
85
     */
86
    String dimensions() default "1";
87
}
88

89
/**
90
 * Binds expressions to local variables in specializations
91
 */
92
@Retention(RetentionPolicy.CLASS)
93
@Target(ElementType.PARAMETER)
94
public @interface Bind {
95
    
96
    /**
97
     * Expression to bind
98
     * @return Binding expression
99
     */
100
    String value();
101
}
102

103
/**
104
 * Marks parameter as shared across specializations
105
 */
106
@Retention(RetentionPolicy.CLASS) 
107
@Target(ElementType.PARAMETER)
108
public @interface Shared {
109
    
110
    /**
111
     * Shared parameter name
112
     * @return Parameter name
113
     */
114
    String value();
115
}
116
```
117

118
**Usage Example:**
119

120
```java
121
public abstract class AddNode extends BinaryNode {
122
    
123
    @Specialization
124
    protected int doInteger(int left, int right) {
125
        return left + right;
126
    }
127
    
128
    @Specialization
129
    protected long doLong(long left, long right) {
130
        return left + right;
131
    }
132
    
133
    @Specialization
134
    protected double doDouble(double left, double right) {
135
        return left + right;
136
    }
137
    
138
    @Specialization(guards = "isString(left) || isString(right)")
139
    protected String doString(Object left, Object right,
140
                             @Cached ToStringNode leftToString,
141
                             @Cached ToStringNode rightToString) {
142
        return leftToString.execute(left) + rightToString.execute(right);
143
    }
144
    
145
    @Fallback
146
    protected Object doGeneric(Object left, Object right) {
147
        throw new UnsupportedOperationException("Cannot add " + left + " and " + right);
148
    }
149
    
150
    protected boolean isString(Object value) {
151
        return value instanceof String;
152
    }
153
}
154
```
155

156
### Node Generation Annotations
157

158
Annotations for controlling code generation and node factory creation.
159

160
```java { .api }
161
/**
162
 * Generates node factory for DSL node
163
 */
164
@Retention(RetentionPolicy.CLASS)
165
@Target(ElementType.TYPE)
166
public @interface GenerateNodeFactory {
167
}
168

169
/**
170
 * Generates uncached version of node
171
 */
172
@Retention(RetentionPolicy.CLASS)
173
@Target(ElementType.TYPE)
174
public @interface GenerateUncached {
175
    
176
    /**
177
     * Whether to inherit from parent node
178
     * @return true to inherit
179
     */
180
    boolean inherit() default true;
181
}
182

183
/**
184
 * Generates inlined version of node
185
 */
186
@Retention(RetentionPolicy.CLASS)
187
@Target(ElementType.TYPE)
188
public @interface GenerateInline {
189
    
190
    /**
191
     * Whether inlining is allowed
192
     * @return true if allowed
193
     */
194
    boolean value() default true;
195
    
196
    /**
197
     * Inline cache limit
198
     * @return Cache limit
199
     */
200
    String inlineByDefault() default "true";
201
}
202

203
/**
204
 * Generates ahead-of-time compilation support
205
 */
206
@Retention(RetentionPolicy.CLASS)
207
@Target(ElementType.TYPE)
208
public @interface GenerateAOT {
209
    
210
    /**
211
     * Whether to exclude from AOT
212
     * @return true to exclude
213
     */
214
    boolean exclude() default false;
215
}
216

217
/**
218
 * Controls node cost calculation
219
 */
220
@Retention(RetentionPolicy.CLASS)
221
@Target(ElementType.TYPE)
222
public @interface NodeInfo {
223
    
224
    /**
225
     * Node cost hint
226
     * @return NodeCost value
227
     */
228
    NodeCost cost() default NodeCost.MONOMORPHIC;
229
    
230
    /**
231
     * Short name for node
232
     * @return Node name
233
     */
234
    String shortName() default "";
235
    
236
    /**
237
     * Description of node functionality
238
     * @return Node description
239
     */
240
    String description() default "";
241
}
242
```
243

244
### Node Structure Annotations
245

246
Annotations for defining node hierarchies and relationships.
247

248
```java { .api }
249
/**
250
 * Declares a child node
251
 */
252
@Retention(RetentionPolicy.CLASS)
253
@Target(ElementType.TYPE)
254
@Repeatable(NodeChildren.class)
255
public @interface NodeChild {
256
    
257
    /**
258
     * Child node name
259
     * @return Node name
260
     */
261
    String value() default "";
262
    
263
    /**
264
     * Child node type
265
     * @return Node class
266
     */
267
    Class<? extends Node> type() default Node.class;
268
    
269
    /**
270
     * Whether child execution is implicit
271
     * @return true if implicit
272
     */
273
    boolean implicit() default false;
274
}
275

276
/**
277
 * Container for multiple NodeChild annotations
278
 */
279
@Retention(RetentionPolicy.CLASS)
280
@Target(ElementType.TYPE)
281
public @interface NodeChildren {
282
    
283
    /**
284
     * Array of child node declarations
285
     * @return NodeChild annotations
286
     */
287
    NodeChild[] value();
288
}
289

290
/**
291
 * Declares a node field
292
 */
293
@Retention(RetentionPolicy.CLASS)
294
@Target(ElementType.TYPE)
295
@Repeatable(NodeFields.class)
296
public @interface NodeField {
297
    
298
    /**
299
     * Field name
300
     * @return Field name
301
     */
302
    String name();
303
    
304
    /**
305
     * Field type
306
     * @return Field class
307
     */
308
    Class<?> type();
309
}
310

311
/**
312
 * Container for multiple NodeField annotations
313
 */
314
@Retention(RetentionPolicy.CLASS)
315
@Target(ElementType.TYPE)
316
public @interface NodeFields {
317
    
318
    /**
319
     * Array of field declarations
320
     * @return NodeField annotations
321
     */
322
    NodeField[] value();
323
}
324

325
/**
326
 * Marks parameter as executed child node result
327
 */
328
@Retention(RetentionPolicy.CLASS)
329
@Target(ElementType.PARAMETER)
330
public @interface Executed {
331
    
332
    /**
333
     * Child node name or index
334
     * @return Child identifier
335
     */
336
    String with() default "";
337
}
338
```
339

340
### Type System Support
341

342
Annotations and classes for defining type systems and type operations.
343

344
```java { .api }
345
/**
346
 * Defines a type system for DSL nodes
347
 */
348
@Retention(RetentionPolicy.CLASS)
349
@Target(ElementType.TYPE)
350
public @interface TypeSystem {
351
    
352
    /**
353
     * Types in the type system hierarchy
354
     * @return Array of type classes
355
     */
356
    Class<?>[] value();
357
}
358

359
/**
360
 * Defines implicit cast between types
361
 */
362
@Retention(RetentionPolicy.CLASS)
363
@Target(ElementType.METHOD)
364
public @interface ImplicitCast {
365
}
366

367
/**
368
 * Defines type cast operation
369
 */
370
@Retention(RetentionPolicy.CLASS)
371
@Target(ElementType.METHOD) 
372
public @interface TypeCast {
373
    
374
    /**
375
     * Source type for cast
376
     * @return Source type class
377
     */
378
    Class<?> value();
379
}
380

381
/**
382
 * Defines type check operation
383
 */
384
@Retention(RetentionPolicy.CLASS)
385
@Target(ElementType.METHOD)
386
public @interface TypeCheck {
387
    
388
    /**
389
     * Type to check
390
     * @return Type class
391
     */
392
    Class<?> value();
393
}
394

395
/**
396
 * Creates type system from annotations
397
 */
398
public abstract class TypeSystemReference {
399
    
400
    /**
401
     * Get type system instance
402
     * @return TypeSystem instance
403
     */
404
    public abstract Object getType();
405
}
406
```
407

408
**Usage Example:**
409

410
```java
411
@TypeSystem({int.class, long.class, double.class, boolean.class, String.class, Object.class})
412
public abstract class MyTypeSystem {
413
    
414
    @ImplicitCast
415
    public static long castIntToLong(int value) {
416
        return value;
417
    }
418
    
419
    @ImplicitCast
420
    public static double castLongToDouble(long value) {
421
        return value;
422
    }
423
    
424
    @TypeCheck(int.class)
425
    public static boolean isInteger(Object value) {
426
        return value instanceof Integer;
427
    }
428
    
429
    @TypeCast(int.class)
430
    public static int asInteger(Object value) {
431
        return (Integer) value;
432
    }
433
}
434
```
435

436
### Library Integration
437

438
Annotations for integrating DSL nodes with Truffle libraries.
439

440
```java { .api }
441
/**
442
 * Caches library instances for efficient dispatch
443
 */
444
@Retention(RetentionPolicy.CLASS)
445
@Target(ElementType.PARAMETER)
446
public @interface CachedLibrary {
447
    
448
    /**
449
     * Expression for library receiver
450
     * @return Receiver expression
451
     */
452
    String value() default "";
453
    
454
    /**
455
     * Cache limit for library instances
456
     * @return Maximum cache size
457
     */
458
    String limit() default "3";
459
}
460
```
461

462
### Error Handling
463

464
Exception types for DSL runtime errors.
465

466
```java { .api }
467
/**
468
 * Exception thrown when no specialization matches
469
 */
470
public final class UnsupportedSpecializationException extends RuntimeException {
471
    
472
    /**
473
     * Create exception with node and values
474
     * @param node Node that failed
475
     * @param suppliedValues Values that caused failure
476
     * @return New exception instance
477
     */
478
    public static UnsupportedSpecializationException create(Node node, Object... suppliedValues);
479
    
480
    /**
481
     * Get node that failed
482
     * @return Node instance
483
     */
484
    public Node getNode();
485
    
486
    /**
487
     * Get supplied values
488
     * @return Array of values
489
     */
490
    public Object[] getSuppliedValues();
491
}
492

493
/**
494
 * Exception for unexpected result types
495
 */
496
public final class UnexpectedResultException extends SlowPathException {
497
    
498
    /**
499
     * Create exception with unexpected result
500
     * @param result Unexpected result value
501
     */
502
    public UnexpectedResultException(Object result);
503
    
504
    /**
505
     * Get unexpected result
506
     * @return Result value
507
     */
508
    public Object getResult();
509
}
510
```
511

512
### Node Factory System
513

514
Interfaces for generated node factories.
515

516
```java { .api }
517
/**
518
 * Factory interface for creating DSL nodes
519
 * @param <T> Node type
520
 */
521
public interface NodeFactory<T extends Node> {
522
    
523
    /**
524
     * Get node class
525
     * @return Node class
526
     */
527
    Class<T> getNodeClass();
528
    
529
    /**
530
     * Get list of execution signatures
531
     * @return List of signatures
532
     */
533
    List<List<Class<?>>> getNodeSignatures();
534
    
535
    /**
536
     * Get list of children classes
537
     * @return List of child types
538
     */
539
    List<Class<? extends Node>> getExecutionSignature();
540
    
541
    /**
542
     * Create node instance
543
     * @param children Child nodes
544
     * @return Node instance
545
     */
546
    T createNode(Object... children);
547
    
548
    /**
549
     * Get uncached node instance
550
     * @return Uncached node
551
     */
552
    T getUncachedInstance();
553
}
554

555
/**
556
 * Interface for nodes that support inlining
557
 */
558
public interface InlineSupport {
559
    
560
    /**
561
     * Create inlined version of node
562
     * @param state Inline state
563
     * @return Inlined node
564
     */
565
    Node createInlined(InlineTarget target);
566
    
567
    /**
568
     * Get inline cost
569
     * @return Inlining cost estimate
570
     */
571
    int getInlinedCost();
572
}
573

574
/**
575
 * State object for inline operations
576
 */
577
public abstract class InlineTarget {
578
    
579
    /**
580
     * Get target class for inlining
581
     * @return Target class
582
     */
583
    public abstract Class<?> getTargetClass();
584
    
585
    /**
586
     * Get frame transfer mode
587
     * @return Transfer mode
588
     */
589
    public abstract FrameTransferMode getFrameTransferMode();
590
}
591

592
/**
593
 * Frame transfer modes for inlining
594
 */
595
public enum FrameTransferMode {
596
    NONE, COPY_ARGUMENTS, MATERIALIZE
597
}
598
```
599

600
## Types
601

602
### DSL Configuration Types
603

604
```java { .api }
605
/**
606
 * Configuration for DSL code generation
607
 */
608
public final class DSLOptions {
609
    
610
    /**
611
     * Default cache limit for specializations
612
     */
613
    public static final int DEFAULT_CACHE_LIMIT = 3;
614
    
615
    /**
616
     * Default polymorphism limit
617
     */
618
    public static final int DEFAULT_POLYMORPHISM_LIMIT = 5;
619
}
620

621
/**
622
 * Metadata for generated specializations
623
 */
624
public abstract class SpecializationData {
625
    
626
    /**
627
     * Check if specialization is active
628
     * @return true if active
629
     */
630
    public abstract boolean isActive();
631
    
632
    /**
633
     * Get specialization method name
634
     * @return Method name
635
     */
636
    public abstract String getMethodName();
637
    
638
    /**
639
     * Get guard expressions
640
     * @return Array of guard expressions
641
     */
642
    public abstract String[] getGuards();
643
}
644
```