tessl/maven-org-graalvm-polyglot--graalvm-sdk

GraalVM Polyglot API for multi-language runtime environments with host-guest interoperability and security controls.

—

Pending

Overview

Eval results

Files

Context and Engine Management

Name: tessl/maven-org-graalvm-polyglot--graalvm-sdk
Author: tessl

Context and Engine are the foundational components for managing polyglot execution environments. The Context represents an isolated execution environment for guest languages, while the Engine provides a shared runtime that manages multiple contexts efficiently.

Context Lifecycle

The Context class manages the execution environment for one or more guest languages with complete isolation and security controls.

Context Creation

// Simple context creation
public static Context create(String... permittedLanguages);

// Builder pattern for advanced configuration
public static Context.Builder newBuilder(String... permittedLanguages);

// Get current context (if any)
public static Context getCurrent();

Usage Examples:

// Single language context
try (Context context = Context.create("js")) {
    // JavaScript execution environment
}

// Multi-language context
try (Context context = Context.create("js", "python", "ruby")) {
    // All three languages available
}

// Builder pattern with configuration
Context context = Context.newBuilder("js")
    .allowHostAccess(HostAccess.EXPLICIT)
    .allowPolyglotAccess(PolyglotAccess.NONE)
    .sandbox(SandboxPolicy.CONSTRAINED)
    .build();

Context Builder Configuration

The Context.Builder provides comprehensive configuration options for security, I/O, and runtime behavior.

public static final class Context.Builder {
    // Engine configuration
    public Context.Builder engine(Engine engine);
    
    // I/O stream configuration
    public Context.Builder out(OutputStream out);
    public Context.Builder err(OutputStream err);
    public Context.Builder in(InputStream in);
    
    // Access policy configuration
    public Context.Builder allowHostAccess(HostAccess hostAccess);
    public Context.Builder allowPolyglotAccess(PolyglotAccess polyglotAccess);
    public Context.Builder allowCreateThread(boolean enabled);
    public Context.Builder allowNativeAccess(boolean enabled);
    public Context.Builder allowCreateProcess(boolean enabled);
    public Context.Builder allowEnvironmentAccess(EnvironmentAccess environmentAccess);
    public Context.Builder allowIO(IOAccess ioAccess);
    public Context.Builder allowAllAccess(boolean enabled);
    
    // Security configuration
    public Context.Builder sandbox(SandboxPolicy sandbox);
    
    // Resource management
    public Context.Builder resourceLimits(ResourceLimits limits);
    
    // Options and properties
    public Context.Builder option(String key, String value);
    public Context.Builder options(Map<String, String> options);
    public Context.Builder arguments(String language, String[] args);
    
    // Build the context
    public Context build();
}

Advanced Configuration Example:

ResourceLimits limits = ResourceLimits.newBuilder()
    .statementLimit(10000, null)
    .build();

Context context = Context.newBuilder("js", "python")
    .allowHostAccess(HostAccess.EXPLICIT)
    .allowPolyglotAccess(PolyglotAccess.NONE)
    .allowIO(IOAccess.NONE)
    .sandbox(SandboxPolicy.CONSTRAINED)
    .resourceLimits(limits)
    .out(System.out)
    .err(System.err)
    .build();

Context Operations

public final class Context implements AutoCloseable {
    // Context lifecycle
    public void enter();
    public void leave();
    public void close();
    public void close(boolean cancelIfExecuting);
    public void interrupt(Duration timeout);
    public void safepoint();
    
    // Language management
    public boolean initialize(String languageId);
    public Engine getEngine();
    
    // Bindings and evaluation (detailed in language-execution.md)
    public Value getBindings(String languageId);
    public Value getPolyglotBindings();
    public Value eval(Source source);
    public Value eval(String languageId, CharSequence source);
    
    // Value conversion
    public Value asValue(Object hostValue);
    
    // Resource management
    public void resetLimits();
}

Context Lifecycle Example:

Context context = Context.create("js");
try {
    context.enter(); // Make context active for current thread
    
    // Perform operations...
    Value result = context.eval("js", "Math.PI * 2");
    
} finally {
    context.leave(); // Always leave context
    context.close();  // Release resources
}

Engine Management

The Engine provides a shared runtime environment that can be used across multiple contexts for efficiency and resource sharing.

Engine Creation

// Simple engine creation
public static Engine create();
public static Engine create(String... permittedLanguages);

// Builder pattern for configuration
public static Engine.Builder newBuilder();
public static Engine.Builder newBuilder(String... permittedLanguages);

// Engine discovery
public static Engine findEngine(String... permittedLanguages);

Engine Builder Configuration

public static final class Engine.Builder {
    // Options and configuration
    public Engine.Builder option(String key, String value);
    public Engine.Builder options(Map<String, String> options);
    
    // I/O stream configuration
    public Engine.Builder out(OutputStream out);
    public Engine.Builder err(OutputStream err);
    
    // Access policies
    public Engine.Builder allowExperimentalOptions(boolean enabled);
    
    // Build the engine
    public Engine build();
}

Engine Operations

public final class Engine implements AutoCloseable {
    // Language and instrument discovery
    public Map<String, Language> getLanguages();
    public Map<String, Instrument> getInstruments();
    public OptionDescriptors getOptions();
    
    // Version information
    public String getVersion();
    public String getImplementationName();
    
    // Resource management
    public void close();
    public void close(boolean cancelIfExecuting);
}

Shared Engine Example:

// Create shared engine
Engine engine = Engine.newBuilder("js", "python")
    .option("engine.WarnInterpreterOnly", "false")
    .build();

// Create multiple contexts sharing the engine
Context context1 = Context.newBuilder("js")
    .engine(engine)
    .build();

Context context2 = Context.newBuilder("python") 
    .engine(engine)
    .build();

// Both contexts share compilation and optimization state
try (context1; context2; engine) {
    // Use contexts...
}

Language and Instrument Metadata

Language Information

public final class Language {
    public String getId();
    public String getName();
    public String getImplementationName();
    public String getVersion();
    public Set<String> getMimeTypes();
    public String getDefaultMimeType();
    public boolean isInteractive();
    public OptionDescriptors getOptions();
}

Language Discovery Example:

Engine engine = Engine.create();
Map<String, Language> languages = engine.getLanguages();

for (Language lang : languages.values()) {
    System.out.printf("Language: %s (%s) v%s%n", 
        lang.getName(), lang.getId(), lang.getVersion());
    System.out.printf("MIME types: %s%n", lang.getMimeTypes());
    System.out.printf("Interactive: %s%n", lang.isInteractive());
}

Instrument Information

public final class Instrument {
    public String getId();
    public String getName();
    public String getVersion();
    public OptionDescriptors getOptions();
    public <T> T lookup(Class<T> type);
}

Resource Management Best Practices

Try-with-Resources Pattern

// Automatic resource cleanup
try (Engine engine = Engine.create();
     Context context = Context.newBuilder("js").engine(engine).build()) {
    
    Value result = context.eval("js", "console.log('Hello World'); 42");
    
} // Automatically closes context and engine

Manual Resource Management

Engine engine = null;
Context context = null;
try {
    engine = Engine.create("js");
    context = Context.newBuilder("js").engine(engine).build();
    
    // Use context...
    
} finally {
    if (context != null) context.close();
    if (engine != null) engine.close();
}

Forced Cleanup

// Force cleanup even if execution is running
context.close(true);  // Cancel any running execution
engine.close(true);   // Force engine shutdown

Thread Safety and Context Switching

Thread-Local Context Management

Context context1 = Context.create("js");
Context context2 = Context.create("python");

// Thread 1
new Thread(() -> {
    context1.enter();
    try {
        context1.eval("js", "console.log('Thread 1')");
    } finally {
        context1.leave();
    }
}).start();

// Thread 2  
new Thread(() -> {
    context2.enter();
    try {
        context2.eval("python", "print('Thread 2')");
    } finally {
        context2.leave();
    }
}).start();

Context Interruption

Context context = Context.create("js");

// In another thread, interrupt long-running execution
new Thread(() -> {
    try {
        Thread.sleep(5000); // Wait 5 seconds
        context.interrupt(Duration.ofSeconds(10)); // Interrupt with timeout
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
}).start();

// Main thread - this might be interrupted
try {
    context.eval("js", "while(true) { /* infinite loop */ }");
} catch (PolyglotException e) {
    if (e.isInterrupted()) {
        System.out.println("Execution was interrupted");
    }
}

Common Types

// Option descriptors for engine/language configuration
public final class OptionDescriptors implements Iterable<OptionDescriptor> {
    public OptionDescriptor get(String name);
    public Iterator<OptionDescriptor> iterator();
}

public final class OptionDescriptor {
    public String getName();
    public String getHelp();
    public OptionCategory getCategory();
    public boolean isDeprecated();
    public Object getDefaultValue();
}

// Option categories
public enum OptionCategory {
    USER,    // User-configurable options
    EXPERT,  // Expert-level options
    DEBUG    // Debug options
}

Install with Tessl CLI

npx tessl i tessl/maven-org-graalvm-polyglot--graalvm-sdk

docs

context-management.md

index.md

io-filesystem.md

language-execution.md

monitoring-management.md