Truffle-DSL changes for the next release

[Christian Humer]

Hi folks,

I just pushed some major changes and additions to Truffle-DSL.

These changes include:

1) A new layout for the generated code which is now enabled by default. The
new layout should reduce the generated code size by ~20%.
2) A new syntax for guard and assumption expressions.
3) A new @Cached annotation to declare specialization local state. It is
now possible to use Truffle-DSL for inline caches.

To get to know the new features I recommend to read the JavaDoc for
@Specialization[1] and @Cached[2]. I've also prepared a set of examples in
the c.o.t.api.dsl.test project [3]. These examples are built as tests so
they can also be debugged for a better understanding.

For a complete list of changes please see the changelog [4].

If you experience any issues, please don't hesitate to contact me.
I also welcome any feedback on the @Cached annotation as well as the new
expression syntax.


[1]
http://hg.openjdk.java.net/graal/graal/file/6135f3a3fa45/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Specialization.java
[2]
http://hg.openjdk.java.net/graal/graal/file/6135f3a3fa45/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Cached.java
[3]
http://hg.openjdk.java.net/graal/graal/file/6135f3a3fa45/graal/com.oracle.truffle.api.dsl.test/src/com/oracle/truffle/api/dsl/test/examples
[4] http://hg.openjdk.java.net/graal/graal/file/6135f3a3fa45/CHANGELOG.md


Breaking changes and migration:

1) Some guard expressions need to be updated to conform to the new
Java-like syntax.

Guard expressions now always need to declare parameters using the parameter
names of the specialization. No parameters or the names of @NodeChild
annotations as parameters cannot be used anymore.
For example:
static boolean isString(Object a, Object b) {return a instanceof String ||
b instanceof String}
@Specialization(guards="isString")
void s(Object a, Object b) {
}

Needs to be changed to:
@Specialization(guards="isString(a, b)")
void s(Object a, Object b) {
}
The old expression "isString" would now bind to a specialization parameter
value "isString" or lookup a non-private field called "isString" in the
Node.

Please also see these changes to SL [5] as a reference.


2) Guards that do not use any dynamic parameters, for example guards
without any parameters, are now invoked just once per specialization (they
are cached). The DSL assumes that they will not change after the first
invocation. This assumption is valid because guard expressions must be
repeatable per node instance with the same input values (see
Specialization#guards). If they do change then the generated code throws an
AssertionError if assertions are enabled (-ea).

I recommend to run all tests and benchmarks with -ea in order to find
violations of this rule.

For example: Simple Language is relying on a side-effecting guard in
SLWriteLocalVariableNode. I needed to add a frame parameter to ensure that
the guard is not cached [6].
We are working on a better solution SLWriteLocalVariableNode (potentially
using Assumptions instead of guards). For now please use the same
workaround if you have a similar problem in your guest language.


3) @ImportGuards was renamed to @ImportStatic

4) @NodeAssumption is deprecated and must be replaced by uses of @NodeField
with Assumption as type.


[5] http://hg.openjdk.java.net/graal/graal/rev/bf846a813688
[6] http://hg.openjdk.java.net/graal/graal/rev/45a24e9ba03b



- Christian Humer