Mercurial > hg > truffle

annotate truffle/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Specialization.java @ 22157:dc83cc1f94f2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Using fully qualified imports
author Jaroslav Tulach <jaroslav.tulach@oracle.com>
date Wed, 16 Sep 2015 11:33:22 +0200
parents 5bc7f7b867ab
children 414e82b9fc35
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
1 /*
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
2 * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
4 *
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
5 * This code is free software; you can redistribute it and/or modify it
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
6 * under the terms of the GNU General Public License version 2 only, as
11279
494b818b527c Adding "Classpath" exception to the classes in the com.oracle.truffle.api and the com.oracle.truffle.api.dsl package.
Thomas Wuerthinger <thomas.wuerthinger@oracle.com>
parents: 11195
diff changeset
7 * published by the Free Software Foundation. Oracle designates this
494b818b527c Adding "Classpath" exception to the classes in the com.oracle.truffle.api and the com.oracle.truffle.api.dsl package.
Thomas Wuerthinger <thomas.wuerthinger@oracle.com>
parents: 11195
diff changeset
8 * particular file as subject to the "Classpath" exception as provided
494b818b527c Adding "Classpath" exception to the classes in the com.oracle.truffle.api and the com.oracle.truffle.api.dsl package.
Thomas Wuerthinger <thomas.wuerthinger@oracle.com>
parents: 11195
diff changeset
9 * by Oracle in the LICENSE file that accompanied this code.
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
10 *
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
11 * This code is distributed in the hope that it will be useful, but WITHOUT
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
14 * version 2 for more details (a copy is included in the LICENSE file that
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
15 * accompanied this code).
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
16 *
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
17 * You should have received a copy of the GNU General Public License version
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
18 * 2 along with this work; if not, write to the Free Software Foundation,
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
20 *
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
22 * or visit www.oracle.com if you need additional information or have any
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
23 * questions.
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
24 */
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
25 package com.oracle.truffle.api.dsl;
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
26
22157
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
27 import com.oracle.truffle.api.Assumption;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
28 import com.oracle.truffle.api.ExactMath;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
29 import com.oracle.truffle.api.frame.Frame;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
30 import com.oracle.truffle.api.frame.MaterializedFrame;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
31 import com.oracle.truffle.api.frame.VirtualFrame;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
32 import com.oracle.truffle.api.nodes.Node;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
33 import java.lang.annotation.ElementType;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
34 import java.lang.annotation.Retention;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
35 import java.lang.annotation.RetentionPolicy;
dc83cc1f94f2 Using fully qualified imports
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 22003
diff changeset
36 import java.lang.annotation.Target;
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
37
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
38 /**
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
39 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
40 * Defines a method of a node subclass to represent one specialization of an operation. Multiple
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
41 * specializations can be defined in a node representing an operation. A specialization defines
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
42 * which kind of input is expected using the method signature and the annotation attributes. The
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
43 * specialized semantics of the operation are defined using the body of the annotated Java method. A
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
44 * specialization method must be declared in a class that is derived from {@link Node} that
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
45 * references a {@link TypeSystem}. At least one specialization must be defined per operation. If no
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
46 * specialization is valid for the given set of input values then an
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
47 * {@link UnsupportedSpecializationException} is thrown instead of invoking any specialization
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
48 * method.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
49 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
50 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
51 * A specialization must have at least as many parameters as there are {@link NodeChild} annotations
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
52 * declared for the enclosing operation node. These parameters are declared in the same order as the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
53 * {@link NodeChild} annotations (linear execution order). We call such parameters dynamic input
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
54 * parameters. Every specialization that is declared within an operation must have an equal number
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
55 * of dynamic input parameters.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
56 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
57 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
58 * The supported kind of input values for a specialization are declared using guards. A
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
59 * specialization may provide declarative specifications for four kinds of guards:
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
60 * <ul>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
61 * <li><b>Type guards</b> optimistically assume the type of an input value. A value that matches the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
62 * type is cast to its expected type automatically. Type guards are modeled using the parameter type
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
63 * of the specialization method. Types used for type guards must be defined in the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
64 * {@link TypeSystem}. If the type of the parameter is {@link Object} then no type guard is used for
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
65 * the dynamic input parameter.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
66 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
67 * <li><b>Expression guards</b> optimistically assume the return value of a user-defined expression
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
68 * to be <code>true</code>. Expression guards are modeled using Java expressions that return a
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
69 * <code>boolean</code> value. If the guard expression returns <code>false</code>, the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
70 * specialization is no longer applicable and the operation is re-specialized. Guard expressions are
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
71 * declared using the {@link #guards()} attribute.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
72 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
73 * <li><b>Event guards</b> trigger re-specialization in case an exception is thrown in the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
74 * specialization body. The {@link #rewriteOn()} attribute can be used to declare a list of such
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
75 * exceptions. Guards of this kind are useful to avoid calculating a value twice when it is used in
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
76 * the guard and its specialization.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
77 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
78 * <li><b>Assumption guards</b> optimistically assume that the state of an {@link Assumption}
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
79 * remains <code>true</code>. Assumptions can be assigned to specializations using the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
80 * {@link #assumptions()} attribute.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
81 * </ul>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
82 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
83 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
84 * The enclosing {@link Node} of a specialization method must have at least one <code>public</code>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
85 * and non-<code>final</code> execute method. An execute method is a method that starts with
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
86 * 'execute'. If all execute methods declare the first parameter type as {@link Frame},
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
87 * {@link VirtualFrame} or {@link MaterializedFrame} then the same frame type can be used as
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
88 * optional first parameter of the specialization. This parameter does not count to the number of
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
89 * dynamic parameters.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
90 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
91 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
92 * A specialization method may declare multiple parameters annotated with {@link Cached}. Cached
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
93 * parameters are initialized and stored once per specialization instantiation. For consistency
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
94 * between specialization declarations cached parameters must be declared last in a specialization
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
95 * method.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
96 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
97 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
98 * If the operation is re-specialized or if it is executed for the first time then all declared
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
99 * specializations of the operation are tried in declaration order until the guards of the first
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
100 * specialization accepts the current input values. The new specialization is then added to the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
101 * chain of current specialization instances which might consist of one (monomorph) or multiple
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
102 * instances (polymorph). If an assumption of an instantiated specialization is violated then
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
103 * re-specialization is triggered again.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
104 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
105 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
106 * With guards in combination with cached parameters it is possible that multiple instances of the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
107 * same specialization are created. The {@link #limit()} attribute can be used to limit the number
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
108 * of instantiations per specialization.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
109 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
110 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
111 * @see NodeChild
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
112 * @see ShortCircuit
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
113 * @see Fallback
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
114 * @see Cached
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
115 * @see TypeSystem
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
116 * @see TypeSystemReference
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
117 * @see UnsupportedSpecializationException
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
118 */
10825
081eac3646d5 Truffle-DSL: Made specializations reflectable at runtime.
Christian Humer <christian.humer@gmail.com>
parents: 10597
diff changeset
119 @Retention(RetentionPolicy.RUNTIME)
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
120 @Target({ElementType.METHOD})
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
121 public @interface Specialization {
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
122
16762
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
123 /**
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
124 * @deprecated do not use anymore. Will get removed in the next release.
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
125 */
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
126 @Deprecated int DEFAULT_ORDER = -1;
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
127
16762
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
128 /**
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
129 * @deprecated use declaration order instead. Will get removed in the next release.
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
130 */
16749
80f9446d4c81 Truffle-DSL: deprecated order and added insertBefore and contains attributes to the Specialization annotation.
Christian Humer <christian.humer@gmail.com>
parents: 11279
diff changeset
131 @Deprecated
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
132 int order() default DEFAULT_ORDER;
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
133
16762
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
134 /**
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
135 * References a specialization of a super class by its method name where this specialization is
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
136 * inserted before. The declaration order of a specialization is not usable for nodes where
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
137 * specializations are partly declared in the super class and partly declared in a derived
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
138 * class. By default all specializations declared in the derived class are appended to those in
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
139 * the super class. This attribute can be used to override the default behavior.
16762
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
140 */
16749
80f9446d4c81 Truffle-DSL: deprecated order and added insertBefore and contains attributes to the Specialization annotation.
Christian Humer <christian.humer@gmail.com>
parents: 11279
diff changeset
141 String insertBefore() default "";
80f9446d4c81 Truffle-DSL: deprecated order and added insertBefore and contains attributes to the Specialization annotation.
Christian Humer <christian.humer@gmail.com>
parents: 11279
diff changeset
142
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
143 /**
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
144 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
145 * Declares an event guards that trigger re-specialization in case an exception is thrown in the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
146 * specialization body. This attribute can be used to declare a list of such exceptions. Guards
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
147 * of this kind are useful to avoid calculating a value twice when it is used in the guard and
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
148 * its specialization.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
149 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
150 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
151 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
152 * If an event guard exception is triggered then all instantiations of this specialization are
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
153 * removed. If one of theses exceptions is thrown once then no further instantiations of this
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
154 * specialization are going to be created for this node. A specialization that rewrites on an
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
155 * exception must ensure that no non-repeatable side-effect is caused until the rewrite is
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
156 * triggered.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
157 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
158 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
159 * <b>Example usage:</b>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
160 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
161 * <pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
162 * &#064;Specialization(rewriteOn = ArithmeticException.class)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
163 * int doAddNoOverflow(int a, int b) {
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
164 * return ExactMath.addExact(a, b);
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
165 * }
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
166 * &#064;Specialization
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
167 * long doAddWithOverflow(int a, int b) {
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
168 * return a + b;
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
169 * }
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
170 * ...
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
171 * Example executions:
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
172 * execute(Integer.MAX_VALUE - 1, 1) => doAddNoOverflow(Integer.MAX_VALUE - 1, 1)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
173 * execute(Integer.MAX_VALUE, 1) => doAddNoOverflow(Integer.MAX_VALUE, 1)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
174 * => throws ArithmeticException
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
175 * => doAddWithOverflow(Integer.MAX_VALUE, 1)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
176 * execute(Integer.MAX_VALUE - 1, 1) => doAddWithOverflow(Integer.MAX_VALUE - 1, 1)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
177 * </pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
178 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
179 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
180 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
181 * @see ExactMath#addExact(int, int)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
182 */
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
183 Class<? extends Throwable>[] rewriteOn() default {};
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
184
16762
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
185 /**
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
186 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
187 * Declares other specializations of the same node to be contained by this specialization. Other
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
188 * specializations are references using their unique method name. If this specialization is
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
189 * instantiated then all contained specialization instances are removed and never instantiated
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
190 * again for this node instance. Therefore this specialization should handle strictly more
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
191 * inputs than which were handled by the contained specialization, otherwise the removal of the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
192 * contained specialization will lead to unspecialized types of input values. The contains
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
193 * declaration is transitive for multiple involved specializations.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
194 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
195 * <b>Example usage:</b>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
196 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
197 * <pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
198 * &#064;Specialization(guards = "b == 2")
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
199 * void doDivPowerTwo(int a, int b) {
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
200 * return a >> 1;
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
201 * }
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
202 * &#064;Specialization(contains ="doDivPowerTwo", guards = "b > 0")
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
203 * void doDivPositive(int a, int b) {
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
204 * return a / b;
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
205 * }
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
206 * ...
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
207 * Example executions with contains="doDivPowerTwo":
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
208 * execute(4, 2) => doDivPowerTwo(4, 2)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
209 * execute(9, 3) => doDivPositive(9, 3) // doDivPowerTwo instances get removed
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
210 * execute(4, 2) => doDivPositive(4, 2)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
211 * Same executions without contains="doDivPowerTwo"
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
212 * execute(4, 2) => doDivPowerTwo(4, 2)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
213 * execute(9, 3) => doDivPositive(9, 3)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
214 * execute(4, 2) => doDivPowerTwo(4, 2)
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
215 * </pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
216 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
217 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
218 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
219 * @see #guards()
16762
ea9903f9684f Truffle-DSL: added some javadoc
Christian Humer <christian.humer@gmail.com>
parents: 16749
diff changeset
220 */
16749
80f9446d4c81 Truffle-DSL: deprecated order and added insertBefore and contains attributes to the Specialization annotation.
Christian Humer <christian.humer@gmail.com>
parents: 11279
diff changeset
221 String[] contains() default {};
80f9446d4c81 Truffle-DSL: deprecated order and added insertBefore and contains attributes to the Specialization annotation.
Christian Humer <christian.humer@gmail.com>
parents: 11279
diff changeset
222
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
223 /**
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
224 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
225 * Declares <code>boolean</code> expressions that define whether or not input values are
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
226 * applicable to this specialization instance. Guard expressions must always return the same
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
227 * result for each combination of the enclosing node instance and the bound input values.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
228 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
229 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
230 * If a guard expression does not bind any dynamic input parameters then the DSL assumes that
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
231 * the result will not change for this node after specialization instantiation. The DSL asserts
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
232 * this assumption if assertions are enabled (-ea).
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
233 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
234 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
235 * Guard expressions are defined using a subset of Java. This subset includes field/parameter
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
236 * accesses, function calls, type exact infix comparisons (==, !=, <, <=, >, >=), logical
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
237 * negation (!), logical disjunction (||) and integer literals. The return type of guard
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
238 * expressions must be <code>boolean</code>. Bound elements without receivers are resolved using
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
239 * the following order:
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
240 * <ol>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
241 * <li>Dynamic and cached parameters of the enclosing specialization.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
242 * <li>Fields defined using {@link NodeField} for the enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
243 * <li>Non-private, static or virtual methods or fields of enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
244 * <li>Non-private, static or virtual methods or fields of super types of the enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
245 * <li>Public and static methods or fields imported using {@link ImportStatic}.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
246 * </ol>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
247 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
248 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
249 * <b>Example usage:</b>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
250 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
251 * <pre>
22003
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
252 * static boolean acceptOperand(int operand) { assert operand <= 42; return operand & 1 ==
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
253 * 1; } &#064;Specialization(guards = {"operand <= 42", "acceptOperand(operand)"}) void
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
254 * doSpecialization(int operand) {...}
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
255 * </pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
256 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
257 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
258 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
259 * @see Cached
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
260 * @see ImportStatic
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
261 */
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
262 String[] guards() default {};
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
263
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
264 /**
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
265 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
266 * Declares assumption guards that optimistically assume that the state of an {@link Assumption}
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
267 * remains valid. Assumption expressions are cached once per specialization instantiation. If
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
268 * one of the returned assumptions gets invalidated then the specialization instance is removed.
19305
48bdad77afcd Truffle-DSL: assumptions javadoc fixes.
Christian Humer <christian.humer@gmail.com>
parents: 19300
diff changeset
269 * If the assumption expression returns an array of assumptions then all assumptions of the
48bdad77afcd Truffle-DSL: assumptions javadoc fixes.
Christian Humer <christian.humer@gmail.com>
parents: 19300
diff changeset
270 * array are checked. This is limited to one-dimensional arrays.
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
271 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
272 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
273 * Assumption expressions are defined using a subset of Java. This subset includes
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
274 * field/parameter accesses, function calls, type exact infix comparisons (==, !=, <, <=, >,
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
275 * >=), logical negation (!), logical disjunction (||) and integer literals. The return type of
19305
48bdad77afcd Truffle-DSL: assumptions javadoc fixes.
Christian Humer <christian.humer@gmail.com>
parents: 19300
diff changeset
276 * the expression must be {@link Assumption} or an array of {@link Assumption} instances.
48bdad77afcd Truffle-DSL: assumptions javadoc fixes.
Christian Humer <christian.humer@gmail.com>
parents: 19300
diff changeset
277 * Assumption expressions are not allowed to bind to dynamic parameter values of the
48bdad77afcd Truffle-DSL: assumptions javadoc fixes.
Christian Humer <christian.humer@gmail.com>
parents: 19300
diff changeset
278 * specialization. Bound elements without receivers are resolved using the following order:
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
279 * <ol>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
280 * <li>Cached parameters of the enclosing specialization.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
281 * <li>Fields defined using {@link NodeField} for the enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
282 * <li>Non-private, static or virtual methods or fields of enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
283 * <li>Non-private, static or virtual methods or fields of super types of the enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
284 * <li>Public and static methods or fields imported using {@link ImportStatic}.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
285 * </ol>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
286 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
287 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
288 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
289 * <b>Example usage:</b>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
290 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
291 * <pre>
22003
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
292 * static abstract class DynamicObject() { abstract Shape getShape(); ... } static
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
293 * abstract class Shape() { abstract Assumption getUnmodifiedAssuption(); ... }
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
294 * &#064;Specialization(guards = "operand.getShape() == cachedShape", assumptions =
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
295 * "cachedShape.getUnmodifiedAssumption()") void doAssumeUnmodifiedShape(DynamicObject
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
296 * operand, @Cached("operand.getShape()") Shape cachedShape) {...}
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
297 * </pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
298 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
299 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
300 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
301 * @see Cached
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
302 * @see ImportStatic
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
303 */
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
304 String[] assumptions() default {};
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
305
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
306 /**
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
307 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
308 * Declares the expression that limits the number of specialization instantiations. The default
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
309 * limit for specialization instantiations is defined as <code>"3"</code>. If the limit is
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
310 * exceeded no more instantiations of the enclosing specialization method are created. Please
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
311 * note that the existing specialization instantiations are <b>not</b> removed from the
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
312 * specialization chain. You can use {@link #contains()} to remove unnecessary specializations
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
313 * instances.
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
314 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
315 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
316 * The limit expression is defined using a subset of Java. This subset includes field/parameter
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
317 * accesses, function calls, type exact infix comparisons (==, !=, <, <=, >, >=), logical
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
318 * negation (!), logical disjunction (||) and integer literals. The return type of the limit
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
319 * expression must be <code>int</code>. Limit expressions are not allowed to bind to dynamic
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
320 * parameter values of the specialization. Bound elements without receivers are resolved using
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
321 * the following order:
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
322 * <ol>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
323 * <li>Cached parameters of the enclosing specialization.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
324 * <li>Fields defined using {@link NodeField} for the enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
325 * <li>Non-private, static or virtual methods or fields of enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
326 * <li>Non-private, static or virtual methods or fields of super types of the enclosing node.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
327 * <li>Public and static methods or fields imported using {@link ImportStatic}.</li>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
328 * </ol>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
329 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
330 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
331 * <p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
332 * <b>Example usage:</b>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
333 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
334 * <pre>
22003
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
335 * static int getCacheLimit() { return
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
336 * Integer.parseInt(System.getProperty("language.cacheLimit")); } &#064;Specialization(guards =
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
337 * "operand == cachedOperand", limit = "getCacheLimit()") void doCached(Object
5bc7f7b867ab Making debugger always on for each TruffleVM execution. Introducing EventConsumer to process such debugger events. Requesting each RootNode to be associated with a TruffleLanguage, so debugger can find out proper context for each Node where executions gets suspended.
Jaroslav Tulach <jaroslav.tulach@oracle.com>
parents: 21951
diff changeset
338 * operand, @Cached("operand") Object cachedOperand) {...}
19288
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
339 * </pre>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
340 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
341 * </p>
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
342 *
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
343 * @see #guards()
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
344 * @see #contains()
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
345 * @see Cached
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
346 * @see ImportStatic
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
347 */
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
348 String limit() default "";
3a37116ef37f Truffle-DSL: added @Cached annotation, added limit property and updated @Specialization javadoc.
Christian Humer <christian.humer@gmail.com>
parents: 16762
diff changeset
349
10597
79041ab43660 Truffle-DSL: API-change: Renamed truffle.api.codegen to truffle.api.dsl for all projects and packages.
Christian Humer <christian.humer@gmail.com>
parents:
diff changeset
350 }