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

Link copied to clipboard

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.

Link copied to clipboard

Functions

Link copied to clipboard
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.

Link copied to clipboard
abstract fun enter()

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

Link copied to clipboard
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.

Link copied to clipboard
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.

Link copied to clipboard
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.

Link copied to clipboard
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.

Link copied to clipboard
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.

Link copied to clipboard
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.

Link copied to clipboard
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.

Link copied to clipboard
abstract fun unwrap(): Context