engine/elide.runtime.core/PolyglotContext

PolyglotContext

The Polyglot Context is the core of the Elide runtime: it evaluates guest code in the embedded VM, returning the execution result. Context instances can be acquired from a PolyglotEngine.

Contexts are fully generic, meaning they do not impose constraints on the nature of the guest code (as long as the requested language is supported by the context), nor do they infer any execution details from it. This allows specific use cases such as SSR to be built using the context API without coupling.

Configuration

Contexts can be configured using plugins that subscribe to the ContextCreated event and update the provided PolyglotContextBuilder.

Plugins are installed into the engine when it is initialized, and will receive an event for every context issued by acquire.

Guest code execution

To evaluate and execute a unit of guest code, call evaluate indicating the target GuestLanguage and source, the returned PolyglotValue will contain the result of the execution, depending on the context configuration.

Types

EvaluationOptions

interface EvaluationOptions

Specifies options related to the evaluate step for a given chunk of guest code; these options can be provided optionally at the call-site to control the behavior of the evaluation.

EvaluationOptionsData

@JvmRecord

data class EvaluationOptionsData : Record, PolyglotContext.EvaluationOptions

Default implementation of EvaluationOptions.

Functions

bindings

abstract fun bindings(language: GuestLanguage? = null): PolyglotValue

Returns the root value that provides intrinsic bindings for the specified language, or all supported languages if language is set to null.

enter

abstract fun enter()

Explicitly enter the context in the current thread. This can reduce the overhead when using evaluate repeatedly.

evaluate

open fun evaluate(source: Source): PolyglotValue

abstract fun evaluate(source: Source, options: PolyglotContext.EvaluationOptions): PolyglotValue

open fun evaluate(source: Source, internals: Boolean): PolyglotValue

Evaluate the given source, returning the result of the execution. Depending on the configuration of the context, this method may fail if the selected language is not enabled in the underlying engine.

evaluate

@DelicateElideApi

fun PolyglotContext.evaluate(language: GuestLanguage, source: String, name: String? = null, internals: Boolean = false, interactive: Boolean = PolyglotDefaults.DEFAULT_INTERACTIVE, cached: Boolean = PolyglotDefaults.DEFAULT_CACHED, uri: URI? = null): PolyglotValue

Evaluate a fragment of source code in the specified language, returning the result of the execution. Depending on the configuration of the context, this method may fail if the language is not enabled in the underlying engine.

get

abstract operator fun <T> get(element: PolyglotContextElement<T>): T?

Returns the value associated with a given context element, or null if the element is not present.

leave

abstract fun leave()

Explicitly leave the context in the current thread. Do not call this method if a high number of evaluate calls is expected; instead, leave once the last call has been received.

parse

abstract fun parse(source: Source): PolyglotValue

Parse the given source without evaluating it, possibly throwing an exception if a syntax error is found. Sources processed in this way may also be cached and reused by later invocations of parse or evaluate.

parse

@DelicateElideApi

fun PolyglotContext.parse(language: GuestLanguage, source: String, name: String? = null, internals: Boolean = false, interactive: Boolean = PolyglotDefaults.DEFAULT_INTERACTIVE, cached: Boolean = PolyglotDefaults.DEFAULT_CACHED, uri: URI? = null): PolyglotValue

Parse a fragment of source code in the specified language, returning the parsed value, which is typically executable. Depending on the configuration of the context, this method may fail if the language is not enabled in the underlying engine.

set

abstract operator fun <T> set(element: PolyglotContextElement<T>, value: T): Boolean

Sets the value associated with a given context element, returning true if a previous value was replaced.

unwrap

abstract fun unwrap(): Context