Runtime Management

/**
 * Main interface for accessing Truffle runtime services
 * Obtained via Truffle.getRuntime()
 */
public abstract class TruffleRuntime {
    /** Creates an optimized call target from a root node */
    public abstract CallTarget createCallTarget(RootNode rootNode);
    
    /** Returns the name of this runtime implementation */
    public abstract String getName();
    
    /** Notifies the runtime of transfer from compiled to interpreted code */
    public abstract void notifyTransferToInterpreter();
    
    /** Checks if profiling is currently enabled */
    public abstract boolean isProfilingEnabled();
    
    /** Creates a new virtual frame for method execution */
    public abstract VirtualFrame createVirtualFrame(Object[] arguments, FrameDescriptor frameDescriptor);
    
    /** Creates a new materialized frame from arguments */
    public abstract MaterializedFrame createMaterializedFrame(Object[] arguments, FrameDescriptor frameDescriptor);
    
    /** Creates a new materialized frame from an existing virtual frame */
    public abstract MaterializedFrame createMaterializedFrame(Object[] arguments);
    
    /** Returns the frame instance currently on the stack */
    public abstract FrameInstance getCurrentFrame();
    
    /** Returns an iterable of all frames currently on the stack */
    public abstract Iterable<FrameInstance> getStackTrace();
    
    /** Creates a new assumption for optimization purposes */
    public abstract Assumption createAssumption();
    
    /** Creates a new assumption with a name for optimization purposes */
    public abstract Assumption createAssumption(String name);
}

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;
import com.oracle.truffle.api.Assumption;

// Get the runtime instance
TruffleRuntime runtime = Truffle.getRuntime();

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

// Check runtime capabilities
if (runtime.isProfilingEnabled()) {
    System.out.println("Profiling is enabled");
}

// Create assumptions for optimization
Assumption validAssumption = runtime.createAssumption("MyOptimization");

/**
 * Abstract base class for Truffle runtime implementations
 */
public abstract class AbstractTruffleRuntime extends TruffleRuntime {
    /** Returns the default call target for root nodes */
    public CallTarget createCallTarget(RootNode rootNode) {
        return createCallTarget(rootNode, CallTarget.class);
    }
    
    /** Creates a call target with specific target class */
    public abstract <T extends CallTarget> T createCallTarget(RootNode rootNode, Class<T> clazz);
}

/**
 * Graal-based implementation of the Truffle runtime
 * Provides optimizing compilation and advanced runtime features
 */
public final class GraalTruffleRuntime extends OptimizedTruffleRuntime {
    /** Returns the singleton instance of the Graal Truffle runtime */
    public static GraalTruffleRuntime getRuntime();
    
    /** Returns the runtime name */
    public String getName();
    
    /** Adds a listener for runtime events */
    public void addListener(GraalTruffleRuntimeListener listener);
    
    /** Removes a runtime event listener */
    public void removeListener(GraalTruffleRuntimeListener listener);
    
    /** Returns statistics about compilation performance */
    public CompilerOptions getCompilerOptions();
    
    /** Forces garbage collection of optimized code */
    public void clearCachedCallTargets();
}

/**
 * Configuration options for the Truffle runtime
 */
public final class TruffleRuntimeOptions {
    /** Maximum number of calls before compilation triggers */
    public static final OptionKey<Integer> COMPILATION_CALL_THRESHOLD = new OptionKey<>(1000);
    
    /** Maximum number of loop iterations before OSR compilation */
    public static final OptionKey<Integer> OSR_COMPILATION_THRESHOLD = new OptionKey<>(100000);
    
    /** Whether to enable compilation statistics */
    public static final OptionKey<Boolean> COMPILATION_STATISTICS = new OptionKey<>(false);
    
    /** Whether to trace compilation events */
    public static final OptionKey<Boolean> TRACE_COMPILATION = new OptionKey<>(false);
    
    /** Action to take when compilation fails */
    public static final OptionKey<CompilationFailureAction> COMPILATION_FAILURE_ACTION = 
        new OptionKey<>(CompilationFailureAction.Silent);
}

public final class OptimizedRuntimeOptions {
    /** Enable background compilation */
    public static final OptionKey<Boolean> BACKGROUND_COMPILATION = new OptionKey<>(true);
    
    /** Number of compiler threads to use */
    public static final OptionKey<Integer> COMPILER_THREADS = new OptionKey<>(2);
    
    /** Whether to enable splitting optimization */
    public static final OptionKey<Boolean> SPLITTING = new OptionKey<>(true);
    
    /** Whether to enable OSR (On Stack Replacement) */
    public static final OptionKey<Boolean> OSR = new OptionKey<>(true);
}

// Access runtime options through the engine
Context context = Context.newBuilder()
    .option("engine.CompilationCallThreshold", "500")
    .option("engine.BackgroundCompilation", "false")
    .build();

// Runtime automatically applies these settings
TruffleRuntime runtime = Truffle.getRuntime();

public interface FrameInstance {
    /** Returns the frame at this stack position */
    Frame getFrame(FrameAccess access);
    
    /** Returns the call node that created this frame */
    Node getCallNode();
    
    /** Returns the call target for this frame */
    CallTarget getCallTarget();
    
    /** Checks if this is a virtual frame */
    boolean isVirtualFrame();
}

public enum FrameAccess {
    /** No frame access required */
    NONE,
    /** Read-only access to frame */
    READ_ONLY,  
    /** Read-write access to frame */
    READ_WRITE,
    /** Materialize the frame */
    MATERIALIZE
}

public abstract class FrameDescriptor {
    /** Creates a new frame descriptor */
    public static FrameDescriptor create();
    
    /** Creates a new frame descriptor with default value */
    public static FrameDescriptor create(Object defaultValue);
    
    /** Adds a new frame slot */
    public abstract FrameSlot addFrameSlot(Object identifier);
    
    /** Finds an existing frame slot by identifier */
    public abstract FrameSlot findFrameSlot(Object identifier);
    
    /** Returns all frame slots */
    public abstract List<? extends FrameSlot> getSlots();
}