Builtin Base Methods
While we strive to implement most of the Enso standard library in Enso itself, it is necessary for certain methods, particularly ones involving operations out of reach for the standard language semantics, or primitive system calls, to be implemented in Java.
To facilitate this process, we have created an annotation-based DSL for easier generation of such methods’ boilerplate.
- DSL Overview
- Structural Requirements
- Generated Node
The Enso Base DSL exposes certain annotations that allow to generate boilerplate
transforming standard Truffle nodes into a shape that can easily be exported to
the Base library. This DSL facilitates automatic parsing and typechecking of
method arguments and wrapping the node in an actual
@BuiltinMethod annotation is applied to a Truffle
Node subclass that
should be treated as a builtin method. It takes the following arguments:
typeString the name of the type the method will be registered on.
nameString the method name.
descriptionString a summary of the method’s behavior, for documentation purposes.
The annotation will generate a
RootNode subclass in the same package as the
declaring node, with a name basing on the declaring node’s name. The name of the
generated node is the name of the original node, with the
Node suffix stripped
MethodGen suffix appended. E.g.
AndOperatorNode will generate a
AndOperatorMethodGen root node.
The DSL places certain structural requirements on the declaring node.
- Construction: The node must be constructible using either a
buildmethod or a parameterless constructor. If a suitable
buildmethod is defined, it will be preferred over the constructor.
- Execution: The node must declare a single, accessible (i.e. at least
package-private), non-void method named
Execute Method Semantics
execute method defined by the declaring node has the following semantics.
- Return type. If the return type is
Stateful, the method is assumed to modify the monadic state. For any other return type, the method cannot modify the monadic state.
- Arguments. The method may take any number of arguments, though at least an
selfmust be present. The arguments have following semantics:
Objectargument may be annotated with
@MonadicState. This tells the DSL to substitute it for the current value of monadic state. Note that this value is read-only. In order to modify state, the method must return a
VirtualFrameargument will be passed the current execution frame.
CallerInfoargument will be passed the current
CallerInfoand mark the method as requiring the caller info at runtime.
- All other arguments are treated as positional arguments to the method.
Note that according to the language specification, any method must take an
this. Because of a naming conflict with Java, this argument is called
_thisin the DSL. Please note that it is mandatory to take an argument called
_this, even if it is unused.
- The positional arguments can be of any typed specified by the runtime type
Object. Arguments typed as
Thunkmark the argument as suspended in the generated function header.
The DSL generates a single root node per annotated class. This node handles reading the arguments from the execution frame and typechecking them, before delegating to the declaring node.
The generated node also defines a static
wrapping the node in a runtime function object.