tessl/maven-org-graalvm-truffle--truffle-api

A multi-language framework for executing dynamic languages that achieves high performance when combined with Graal.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Truffle API

Name: tessl/maven-org-graalvm-truffle--truffle-api
Author: tessl

Truffle is a multi-language framework for executing dynamic languages that achieves high performance when combined with Graal. It provides a comprehensive API for implementing dynamic language runtimes on the JVM with advanced optimization features including JIT compilation, profiling, debugging, and cross-language interoperability.

Package Information

Package Name: org.graalvm.truffle:truffle-api
Package Type: maven
Language: Java
Installation: <dependency><groupId>org.graalvm.truffle</groupId><artifactId>truffle-api</artifactId><version>23.1.3</version></dependency>
Java Compliance: 17+

Core Imports

import com.oracle.truffle.api.TruffleLanguage;
import com.oracle.truffle.api.nodes.Node;
import com.oracle.truffle.api.nodes.RootNode;
import com.oracle.truffle.api.frame.VirtualFrame;
import com.oracle.truffle.api.interop.InteropLibrary;

Basic Usage

import com.oracle.truffle.api.TruffleLanguage;
import com.oracle.truffle.api.nodes.RootNode;
import com.oracle.truffle.api.frame.VirtualFrame;

@TruffleLanguage.Registration(id = "mylang", name = "MyLanguage")
public final class MyLanguage extends TruffleLanguage<MyContext> {
    
    @Override
    protected MyContext createContext(Env env) {
        return new MyContext(env);
    }
    
    @Override
    protected CallTarget parse(ParsingRequest request) throws Exception {
        // Parse source and create AST
        RootNode rootNode = new MyRootNode(this);
        return rootNode.getCallTarget();
    }
}

// Example AST node
public class MyRootNode extends RootNode {
    
    protected MyRootNode(TruffleLanguage<?> language) {
        super(language);
    }
    
    @Override
    public Object execute(VirtualFrame frame) {
        // Execute language logic
        return "Hello, Truffle!";
    }
}

Architecture

Truffle is built around several key architectural components:

Language Implementation Framework: Core abstractions for implementing dynamic languages (TruffleLanguage, contexts, environments)
Abstract Syntax Tree (AST) System: Node-based tree structures for representing and executing code (Node, RootNode, execution frames)
Domain-Specific Language (DSL): Annotation-driven code generation for optimized node implementations and specializations
Interoperability System: Cross-language integration enabling seamless interaction between different Truffle languages
Instrumentation Framework: Debugging, profiling, and tooling infrastructure for language development and runtime analysis
Optimization Infrastructure: Profiling, assumption management, and compiler integration for high-performance execution

Capabilities

Core Language Implementation

Essential classes and interfaces for implementing Truffle-based dynamic languages, including language registration, context management, and basic execution infrastructure.

@TruffleLanguage.Registration(id = "mylang", name = "MyLanguage")
public abstract class TruffleLanguage<C> {
    protected abstract C createContext(Env env);
    
    protected abstract CallTarget parse(ParsingRequest request) throws Exception;
    
    public static final class Env {
        public TruffleFile getInternalTruffleFile(String path);
        public TruffleLogger getLogger(String loggerName);
        public void registerService(Object service);
    }
}

public abstract class RootNode extends Node {
    public abstract Object execute(VirtualFrame frame);
    
    public final CallTarget getCallTarget();
    public final String getName();
}

public interface CallTarget {
    Object call(Object... arguments);
}

Core API

AST Nodes and Execution Framework

Node-based abstract syntax tree system with execution frames, source location tracking, and tree manipulation utilities.

public abstract class Node implements NodeInterface, Cloneable {
    public final <T extends Node> T replace(T newNode);
    public final NodeCost getCost();
    
    protected final void notifyInserted(Node newChild);
    
    public final SourceSection getSourceSection();
}

public interface VirtualFrame extends Frame {
    Object[] getArguments();
    
    FrameDescriptor getFrameDescriptor();
    
    Object getObject(FrameSlot slot) throws FrameSlotTypeException;
    void setObject(FrameSlot slot, Object value);
}

public final class FrameDescriptor {
    public FrameSlot addFrameSlot(Object identifier);
    public FrameSlot findFrameSlot(Object identifier);
}

Core API

Domain-Specific Language (DSL)

Annotation-driven system for generating optimized node implementations with automatic specialization, caching, and fallback handling.

@NodeChild("leftNode")
@NodeChild("rightNode") 
public abstract class AddNode extends BinaryNode {
    
    @Specialization
    protected int doInteger(int left, int right) {
        return left + right;
    }
    
    @Specialization
    protected double doDouble(double left, double right) {
        return left + right;  
    }
    
    @Fallback
    protected Object doGeneric(Object left, Object right) {
        // Handle other types
        return InteropLibrary.getFactory().getUncached().execute(left, "+", right);
    }
}

@GenerateNodeFactory
@NodeChild("arguments")
public abstract class CallNode extends Node {
    
    @Specialization(guards = "function.getCallTarget() == cachedTarget")
    protected Object doDirect(VirtualFrame frame, TruffleObject function,
                             @Cached("function.getCallTarget()") CallTarget cachedTarget,
                             @Cached DirectCallNode callNode) {
        return callNode.call(frame.getArguments());
    }
}

Domain-Specific Language

Cross-Language Interoperability

Comprehensive interoperability system enabling seamless integration between different Truffle languages through message-based protocols and shared object representations.

public abstract class InteropLibrary extends Library {
    public abstract boolean hasArrayElements(Object receiver);
    public abstract Object readArrayElement(Object receiver, long index) throws UnsupportedMessageException, InvalidArrayIndexException;
    public abstract void writeArrayElement(Object receiver, long index, Object value) throws UnsupportedMessageException, UnsupportedTypeException, InvalidArrayIndexException;
    
    public abstract boolean hasMembers(Object receiver);
    public abstract Object getMembers(Object receiver, boolean includeInternal) throws UnsupportedMessageException;
    public abstract Object readMember(Object receiver, String member) throws UnsupportedMessageException, UnknownIdentifierException;
    
    public abstract boolean isExecutable(Object receiver);
    public abstract Object execute(Object receiver, Object... arguments) throws UnsupportedTypeException, ArityException, UnsupportedMessageException;
}

public interface TruffleObject {
    // Marker interface for interoperable objects
}

@ExportLibrary(InteropLibrary.class)
public class MyObject implements TruffleObject {
    
    @ExportMessage
    boolean hasMembers() {
        return true;
    }
    
    @ExportMessage
    Object readMember(String member) throws UnknownIdentifierException {
        // Return member value
        return getMember(member);
    }
}

Interoperability

Instrumentation and Debugging

Comprehensive debugging and profiling infrastructure for language development, runtime analysis, and tooling integration.

public abstract class TruffleInstrument {
    
    protected abstract void onCreate(Env env);
    
    public static final class Env {
        public Instrumenter getInstrumenter();
        public TruffleLogger getLogger(String loggerName);
        public void registerService(Object service);
    }
}

public abstract class Instrumenter {
    public <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(
            SourceSectionFilter filter, T factory);
            
    public EventBinding<ExecutionEventListener> attachExecutionEventListener(
            SourceSectionFilter filter, ExecutionEventListener listener);
    
    public AllocationReporter getAllocationReporter();
}

public abstract class ExecutionEventNode extends Node {
    protected void onEnter(VirtualFrame frame) {}
    protected void onReturnValue(VirtualFrame frame, Object result) {}
    protected void onReturnExceptional(VirtualFrame frame, Throwable exception) {}
}

Instrumentation and Debugging

Data Types and Performance

Specialized data types, profiling utilities, and performance optimization features for high-performance language implementations.

public final class TruffleString extends AbstractTruffleString {
    public static TruffleString fromJavaStringUncached(String javaString, Encoding encoding);
    
    public String toJavaStringUncached();
    public int codePointLengthUncached(Encoding encoding);
    
    public TruffleString concatUncached(TruffleString other, Encoding encoding, boolean lazy);
    public TruffleString substringUncached(int fromIndex, int length, Encoding encoding, boolean lazy);
}

public abstract class ValueProfile extends Profile {
    public abstract <T> T profile(T value);
    
    public static ValueProfile createIdentityProfile();
    public static ValueProfile createClassProfile();
}

public abstract class ConditionProfile extends Profile {
    public abstract boolean profile(boolean value);
    
    public static ConditionProfile createBinaryProfile();
    public static ConditionProfile createCountingProfile();
}

Data Types and Performance

Advanced Features

Advanced capabilities including library-based dispatch, static object layouts, and runtime utilities for sophisticated language implementations.

@GenerateLibrary
public abstract class MyLibrary extends Library {
    
    public boolean accepts(Object receiver) {
        return receiver instanceof MyObject;
    }
    
    public abstract Object executeMethod(Object receiver, String methodName, Object[] args);
}

public abstract class StaticShape<T> {
    public abstract StaticProperty getProperty(Object propertyName);
    public abstract T newInstance();
    
    public static <T> Builder<T> newBuilder(TruffleLanguage<?> language);
    
    public static final class Builder<T> {
        public Builder<T> property(StaticProperty property, Class<?> type, boolean isFinal);
        public StaticShape<T> build();
    }
}

public final class AssumedValue<T> {
    public AssumedValue(String name, T initialValue);
    
    public T get();
    public void set(T newValue);
    
    public Assumption getAssumption();
}

Advanced Features

Types

Core Framework Types

public final class TruffleContext {
    public Object eval(Source source);
    public void close();
    public boolean isClosed();
}

public final class Source {
    public static Source newBuilder(String language, String text, String name).build();
    
    public String getCharacters();
    public String getName();
    public String getLanguage();
}

public final class SourceSection {
    public Source getSource();
    public int getStartLine();
    public int getStartColumn();
    public int getEndLine(); 
    public int getEndColumn();
}

Exception Handling Types

public abstract class AbstractTruffleException extends RuntimeException implements TruffleObject {
    protected AbstractTruffleException();
    protected AbstractTruffleException(String message);
    protected AbstractTruffleException(String message, Throwable cause);
    
    public final int getStackTraceElementLimit();
}

public class InteropException extends AbstractTruffleException {
    // Base class for interop exceptions
}

public final class UnsupportedMessageException extends InteropException {
    public static UnsupportedMessageException create();
}