or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

compilation-optimization.mdframes.mdindex.mdinteroperability.mdlanguage-spi.mdmonitoring-profiling.mdnodes.mdruntime-management.mdservice-provider-framework.md
tile.json

tessl/maven-org-graalvm-truffle--truffle-runtime

The community edition of the Truffle runtime providing execution engine and optimization support for dynamic programming languages built with the Truffle framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.graalvm.truffle/truffle-runtime@24.2.x

To install, run

npx @tessl/cli install tessl/maven-org-graalvm-truffle--truffle-runtime@24.2.0

index.mddocs/

Truffle Runtime

The Truffle Runtime is the core execution engine for dynamic programming languages built with the Truffle framework. It provides runtime support, compilation services, optimization infrastructure, and language interoperability capabilities. The runtime automatically compiles and optimizes Abstract Syntax Trees (ASTs) into high-performance native code through integration with the Graal compiler.

Package Information

  • Package Name: org.graalvm.truffle:truffle-runtime
  • Package Type: maven
  • Language: Java
  • Installation: Add to Maven dependencies: 
    <dependency>
  <groupId>org.graalvm.truffle</groupId>
  <artifactId>truffle-runtime</artifactId>
  <version>24.2.1</version>
</dependency>

Core Imports

import com.oracle.truffle.api.Truffle;
import com.oracle.truffle.api.TruffleRuntime;
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.frame.Frame;
import com.oracle.truffle.api.interop.InteropLibrary;
import com.oracle.truffle.api.TruffleLanguage;

Note: The runtime is typically accessed through the Truffle API rather than direct imports. Direct use of runtime classes is generally not recommended for language implementers.

Basic Usage

import com.oracle.truffle.api.Truffle;
import com.oracle.truffle.api.TruffleRuntime;
import com.oracle.truffle.api.nodes.RootNode;
import com.oracle.truffle.api.CallTarget;

// Access the runtime through the Truffle API
TruffleRuntime runtime = Truffle.getRuntime();

// Create a call target from a root node
RootNode rootNode = new MyLanguageRootNode();
CallTarget callTarget = runtime.createCallTarget(rootNode);

// The runtime automatically handles compilation and optimization
Object result = callTarget.call();

Architecture

The Truffle Runtime is built around several key components:

  • Runtime Core: Main execution engine and service provider framework
  • Compilation System: Integration with Graal compiler for optimized code generation
  • Optimization Engine: Assumptions, profiles, and adaptive compilation strategies
  • Monitoring System: Java Flight Recorder integration and performance event tracking
  • Service Framework: Extensible SPI system for custom runtime behaviors

Capabilities

Runtime Management

Core runtime services for accessing the execution engine, creating call targets, and managing runtime options.

public abstract class TruffleRuntime {
    public abstract CallTarget createCallTarget(RootNode rootNode);
    public abstract String getName();
    public abstract void notifyTransferToInterpreter();
    public abstract boolean isProfilingEnabled();
}

Runtime Management

Node Framework

Abstract Syntax Tree (AST) node framework providing the foundation for building executable language interpreters with optimization support.

public abstract class Node {
    public final Node getParent();
    public final <T extends Node> T replace(T newNode);
    public final RootNode getRootNode();
    public SourceSection getSourceSection();
}

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

Node Framework

Frame Management

Execution frame system providing efficient storage and access to method arguments, local variables, and temporary values.

public interface VirtualFrame extends Frame {
    Object[] getArguments();
    MaterializedFrame materialize();
    Object getObject(FrameSlot slot) throws FrameSlotTypeException;
    void setObject(FrameSlot slot, Object value);
    int getInt(FrameSlot slot) throws FrameSlotTypeException;
    void setInt(FrameSlot slot, int value);
}

Frame Management

Language Implementation SPI

Service Provider Interface (SPI) for implementing programming languages on the Truffle framework.

public abstract class TruffleLanguage<C> {
    protected abstract C createContext(Env env);
    protected abstract CallTarget parse(ParsingRequest request) throws Exception;
    protected Object findMetaObject(C context, Object value);
}

@Registration(id = "mylang", name = "My Language", version = "1.0")
public class MyLanguage extends TruffleLanguage<MyLanguageContext> {
    // Implementation
}

Language Implementation SPI

Interoperability

Language interoperability framework enabling seamless interaction between different programming languages through the InteropLibrary protocol.

public abstract class InteropLibrary extends Library {
    public boolean isNull(Object receiver);
    public boolean isExecutable(Object receiver);
    public Object execute(Object receiver, Object... arguments);
    public boolean hasMembers(Object receiver);
    public Object readMember(Object receiver, String member);
    public void writeMember(Object receiver, String member, Object value);
}

Interoperability

Compilation and Optimization

Compilation infrastructure providing optimized call targets, compiler directives, and assumption-based optimizations.

public abstract class OptimizedCallTarget implements CallTarget {
    public abstract boolean isValid();
    public abstract void invalidate();
    public abstract int getCallCount();
    public abstract long getCompilationTime();
    public abstract boolean isCompiling();
}

public final class CompilerDirectives {
    public static void transferToInterpreter();
    public static void transferToInterpreterAndInvalidate();
    public static boolean inInterpreter();
    public static boolean inCompiledCode();
    public static boolean isCompilationConstant(Object value);
}

Compilation and Optimization

Service Provider Framework

Extensible SPI system allowing customization of runtime behaviors including loop node creation, engine caching, and type system integration.

public interface LoopNodeFactory {
    LoopNode createLoopNode(RepeatingNode repeatingNode);
}

public interface EngineCacheSupport {
    <T> T getEngineCache(Object key, Supplier<T> valueSupplier);
    void clearEngineCache();
}

public interface TruffleTypes {
    Class<?> getJavaClass(Object value);
    String getJavaClassName(Object value);
}

Service Provider Framework

Monitoring and Profiling

Comprehensive monitoring capabilities including Java Flight Recorder integration, performance event tracking, and runtime listeners.

public interface GraalTruffleRuntimeListener {
    void onCompilationQueued(OptimizedCallTarget callTarget);
    void onCompilationStarted(OptimizedCallTarget callTarget);
    void onCompilationTruffleTierFinished(OptimizedCallTarget callTarget, TruffleTierContext context, GraphInfo graph);
    void onCompilationGraalTierFinished(OptimizedCallTarget callTarget, GraphInfo graph);
    void onCompilationSuccess(OptimizedCallTarget callTarget, TruffleTierContext context, GraphInfo graph, CompilationResultInfo info, int tier);
    void onCompilationFailed(OptimizedCallTarget callTarget, String reason, boolean bailout, boolean permanentBailout, int tier);
}

Monitoring and Profiling

Common Types

public abstract class CallTarget {
    public abstract Object call(Object... arguments);
}

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

public interface VirtualFrame extends Frame {
    Object[] getArguments();
    MaterializedFrame materialize();
}

public interface MaterializedFrame extends Frame {
    // Persistent frame that can exist beyond call stack
}

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

public abstract class FrameDescriptor {
    public static FrameDescriptor create();
    public abstract FrameSlot addFrameSlot(Object identifier);
    public abstract FrameSlot findFrameSlot(Object identifier);
}

public abstract class FrameSlot {
    public abstract Object getIdentifier();
    public abstract int getIndex();
}

public final class FrameSlotTypeException extends SlowPathException {
    // Exception for wrong slot type access
}

public interface LoopNode {
    void execute(VirtualFrame frame);
    RepeatingNode getRepeatingNode();
}

public interface RepeatingNode {
    boolean executeRepeating(VirtualFrame frame);
}

public interface Library {
    boolean accepts(Object receiver);
}

public enum CompilationFailureAction {
    Silent,
    Print,
    Throw,
    ExitVM,
    Diagnose
}

public final class SourceSection {
    public Source getSource();
    public int getStartLine();
    public int getStartColumn();
    public CharSequence getCharacters();
}