• Home
• org.pkl-lang
• pkl-config-java-all
• 0.27.0
• source code
• Context.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.pkl.thirdparty.graalvm.polyglot.Context Maven / Gradle / Ivy

/*
 * Copyright (c) 2017, 2023, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * The Universal Permissive License (UPL), Version 1.0
 *
 * Subject to the condition set forth below, permission is hereby granted to any
 * person obtaining a copy of this software, associated documentation and/or
 * data (collectively the "Software"), free of charge and under any and all
 * copyright rights in the Software, and any and all patent rights owned or
 * freely licensable by each licensor hereunder covering either (i) the
 * unmodified Software as contributed to or provided by such licensor, or (ii)
 * the Larger Works (as defined below), to deal in both
 *
 * (a) the Software, and
 *
 * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
 * one is included with the Software each a "Larger Work" to which the Software
 * is contributed by such licensors),
 *
 * without restriction, including without limitation the rights to copy, create
 * derivative works of, display, perform, and distribute the Software and make,
 * use, sell, offer for sale, import, export, have made, and have sold the
 * Software and the Larger Work(s), and to sublicense the foregoing rights on
 * either these or other terms.
 *
 * This license is subject to the following condition:
 *
 * The above copyright notice and either this complete permission notice or at a
 * minimum a reference to the UPL must be included in all copies or substantial
 * portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
package org.pkl.thirdparty.graalvm.polyglot;

import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Path;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.Objects;
import java.util.concurrent.TimeoutException;
import java.util.function.Predicate;
import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.stream.StreamSupport;

import org.pkl.thirdparty.graalvm.polyglot.impl.AbstractPolyglotImpl.IOAccessor;
import org.pkl.thirdparty.graalvm.polyglot.impl.AbstractPolyglotImpl.AbstractContextDispatch;
import org.pkl.thirdparty.graalvm.polyglot.impl.AbstractPolyglotImpl.LogHandler;
import org.pkl.thirdparty.graalvm.polyglot.io.FileSystem;
import org.pkl.thirdparty.graalvm.polyglot.io.IOAccess;
import org.pkl.thirdparty.graalvm.polyglot.io.MessageTransport;
import org.pkl.thirdparty.graalvm.polyglot.io.ProcessHandler;
import org.pkl.thirdparty.graalvm.polyglot.proxy.Proxy;

/**
 * A polyglot context for Graal guest languages that allows to {@link #eval(Source) evaluate} code.
 * A polyglot context represents the global runtime state of all {@link Engine#getLanguages()
 * installed} and {@link #newBuilder(String...) permitted} languages. Permitted languages are
 * {@link #initialize(String) initialized} lazily, when they are used for the first time. For many
 * context operations, a language identifier needs to be specified. A language identifier is
 * unique for each language.
 *
 * 
Evaluation
 *
 * A context allows to evaluate a guest language source code using {@link #eval(Source)}. This is
 * possible by evaluating {@link Source} objects or a given language identifier and code
 * {@link String}. The {@link #eval(Source) evaluation} returns either the result value or throws a
 * {@link PolyglotException} if a guest language error occurs.
 * 

 * Example for evaluation of a fragment of JavaScript code with a new context:
 *
 * 
 * Context context = Context.create();
 * Value result = context.eval("js", "42");
 * assert result.asInt() == 42;
 * context.close();
 * 
 *
 * In this example:
 * 

 * 
First we create a new context with all permitted languages.
 * 
Next, we evaluate the expression "42" with language "js", which is the language identifier
 * for JavaScript. Since this is the first time we access JavaScript, it automatically gets
 * {@link #initialize(String) initialized}.
 * 
Then, we assert the result value by converting the result value as primitive int
 * .
 * 
Finally, if the context is no longer needed, it is necessary to close it to ensure that all
 * resources are freed. Contexts are also {@link AutoCloseable} for use with the Java
 * {@code try-with-resources} statement.
 * 
 *
 * 
Configuration
 * 

 * Contexts may be created either with default configuration using the {@link #create(String...)
 * create method} or with custom configuration using the {@link #newBuilder(String...) builder}.
 * Both methods allow to specify a subset of the installed languages as permitted languages. If no
 * language is specified then all installed languages are permitted. Using the builder method
 * {@link Builder#in(InputStream) input}, {@link Builder#err(OutputStream) error} and
 * {@link Builder#out(OutputStream) output} streams, {@link Builder#option(String, String) options},
 * and {@link Builder#arguments(String, String[]) application arguments} may be configured.
 * 

 * Options may be specified for {@link Engine#getLanguages() languages},
 * {@link Engine#getInstruments() instruments}, the {@link Engine#getOptions() engine} and the
 * {@link Engine#getOptions() compiler}. For {@link Language#getOptions() language options}, the
 * option key consists of the {@link Language#getId() language id} plus a dot followed by the option
 * name (e.g. "js.Strict"). For most languages the option names start with an upper-case letter by
 * convention. A list of available options may be received using {@link Language#getOptions()}.
 * {@link Instrument#getOptions() Instrument options} are structured in the same way as language
 * options but start with the {@link Instrument#getId() instrument id} instead.
 * 

 * If system properties are {@link Engine.Builder#useSystemProperties(boolean) enabled}, which they
 * are by default, then all polyglot options maybe specified with the prefix "polyglot." (e.g.
 * "-Dpolyglot.js.Strict=true"). The system properties are read only once when the context or engine
 * instance is created. After that, changes to the system properties have no affect.
 * 

 * Each Graal language performs an initialization step before it can be used to execute code, after
 * which it remains initialized for the lifetime of the context. Initialization is by default lazy
 * and automatic, but initialization can be forced {@link Context#initialize(String) manually} if
 * needed.
 * 

 * Example for custom configuration using the context builder:
 *
 * 
 * OutputStream myOut = new BufferedOutputStream()
 * Context context = Context.newBuilder("js", "R")
 *                          .out(myOut)
 *                          .option("js.Strict", "true")
 *                          .allowAllAccess(true)
 *                          .build();
 * context.eval("js", "42");
 * context.eval("R", "42");
 * context.close();
 * 
 *
 * In this example:
 * 

 * 
At first, we create a new context and specify permitted languages as parameters.
 * 
Secondly, we set the standard output stream to be used for the context.
 * 
Then, we specify an option for JavaScript language only, by structuring the option key with
 * the language id followed by the option name;
 * 
With {@link Builder#allowAllAccess(boolean)} we grant a new context instance with the same
 * access privileges as the host virtual machine.
 * 
Next, we evaluate the expression "42" with language "js", which is the language identifier
 * for JavaScript. Since this is the first time we access JavaScript, it first gets
 * {@link #initialize(String) initialized} as well.
 * 
Similarly to the previous line, the R language expression gets evaluated.
 * 
Finally, we close the context, since it is no longer needed, to free all allocated resources.
 * Contexts are also {@link AutoCloseable} for use with the Java {@code try-with-resources}
 * statement.
 * 
 *
 * 
Bindings
 *
 * The symbols of the top-most scope of a language can be accessed using the
 * {@link #getBindings(String) language bindings}. Each language provides its own bindings object
 * for a context. The bindings object may be used to read, modify, insert and delete members in the
 * top-most scope of the language. Certain languages may not allow write access to the bindings
 * object. See {@link #getBindings(String)} for details.
 * 

 * A context instance also provides access to the {@link #getPolyglotBindings() polyglot} bindings.
 * The polyglot bindings are shared between languages and may be used to exchange values. See
 * {@link #getPolyglotBindings()} for details.
 * 

 * Examples using language bindings from JavaScript:
 *
 * 
 * Context context = Context.create("js");
 * Value jsBindings = context.getBindings("js")
 *
 * jsBindings.putMember("foo", 42);
 * assert context.eval("js", "foo").asInt() == 42;
 *
 * context.eval("js", "var bar = 42");
 * assert jsBindings.getMember("bar").asInt() == 42;
 *
 * assert jsBindings.getMember("Math")
 *                  .getMember("abs")
 *                  .execute(-42)
 *                  .asInt() == 42;
 * context.close();
 * 
 *
 * In this example:
 * 

 * 
We create a new context with JavaScript as the only permitted language.
 * 
Next, we load the JavaScript bindings object and assign it to a local variable
 * jsBindings.
 * 
Then, we insert a new member foo into to the bindings object and verify that the
 * object is accessible within the language by reading from a global symbol with the same name.
 * 
After that, we declare a new global variable in JavaScript and verify that it is accessible
 * as member of the language bindings object.
 * 
Next, we access we access a JavaScript builtin named Math.abs symbol and execute
 * it with -42. This result is asserted to be 42.
 * 
Finally, we close the context to free all allocated resources.
 * 
 *
 * 
Host Interoperability
 *
 * It is often necessary to interact with values of the host runtime and Graal guest languages. Such
 * objects are referred to as host objects. Every Java value that is passed to a Graal
 * language is interpreted according to the specification described in {@link #asValue(Object)}.
 * Also see {@link Value#as(Class)} for further details.
 * 

 * By default only public classes, methods, and fields that are annotated with
 * {@link HostAccess.Export @HostAccess.Export} are accessible to the guest language. This policy
 * can be customized using {@link Builder#allowHostAccess(HostAccess)} when constructing the
 * context.
 *
 * 

 * Example using a Java object from JavaScript:
 *
 * 
 * public class JavaRecord {
 *     @HostAccess.Export public int x;
 *
 *     @HostAccess.Export
 *     public String name() {
 *         return "foo";
 *     }
 * }
 * Context context = Context.create();
 *
 * JavaRecord record = new JavaRecord();
 * context.getBindings("js").putMember("javaRecord", record);
 *
 * context.eval("js", "javaRecord.x = 42");
 * assert record.x == 42;
 *
 * context.eval("js", "javaRecord.name()").asString().equals("foo");
 * 
 *
 * 
Error Handling
 *
 * Program execution may fail when executing a guest language code or when accessing guest language
 * object. Almost all methods in the {@link Context} and {@link Value} API throw a
 * {@link PolyglotException} in case an error occurs. See {@link PolyglotException} for further
 * details on error handling.
 *
 * 
Isolation
 *
 * Each context is by default isolated from all other instances with respect to both language
 * evaluation semantics and resource consumption. By default, a new context instance has no access
 * to host resources, like threads, files or loading new host classes. To allow access to such
 * resources either the individual access right must be granted or
 * {@link Builder#allowAllAccess(boolean) all access} must be set to true.
 *
 * 

 * Contexts can be {@linkplain Builder#engine(Engine) configured} to share certain system resources
 * like ASTs or optimized code by specifying a single underlying engine. See {@link Engine} for more
 * details about code sharing.
 *
 * 

 * Context can be configured to allow value sharing between multiple contexts (allowed by default).
 * See {@link Builder#allowValueSharing(boolean)} for details.
 *
 * 
Proxies
 *
 * The {@link Proxy proxy interfaces} allow to mimic guest language objects, arrays, executables,
 * primitives and native objects in Graal languages. Every Graal language will treat proxy instances
 * like objects of that particular language. Multiple proxy interfaces can be implemented at the
 * same time. For example, it is useful to provide proxy values that are objects with members and
 * arrays at the same time.
 *
 * 
Thread-Safety
 *
 * It is safe to use a context instance from a single thread. It is also safe to use it with
 * multiple threads if they do not access the context at the same time. Whether a single context
 * instance may be used from multiple threads at the same time depends on if all initialized
 * languages support it. If initialized languages support multi-threading, then the context instance
 * may be used from multiple threads at the same time. If a context is used from multiple threads
 * and the language does not fit, then an {@link IllegalStateException} is thrown by the accessing
 * method.
 * 

 * Meta-data from the context's underlying {@link #getEngine() engine} can be retrieved safely by
 * any thread at any time.
 * 

 * A context may be {@linkplain #close() closed} from any thread, but only if the context is not
 * currently executing code. If the context is currently executing some code, a different thread may
 * kill the running execution and close the context using {@link #close(boolean)}.
 *
 * 
Context Exit
 *
 * A context is exited naturally by calling the {@link #close} method. A context may also be exited
 * at the guest application request. There are two ways a guest language may exit.
 * 

 * 
Soft exit. A guest language throws a special exception that causes the embedder thread to
 * eventually throw a {@link PolyglotException} with {@link PolyglotException#isExit()} returning
 * true and {@link PolyglotException#getExitStatus()} returning the exit status code
 * specified by the guest application. The special exception does not influence other threads and
 * does not trigger context close on its own. Closing the context is up to the embedder.
 * 
Hard exit. A guest language uses a builtin command that unwinds all context threads and
 * closes the context by force. Embedder threads also throw a {@link PolyglotException} with
 * {@link PolyglotException#isExit()} returning true and
 * {@link PolyglotException#getExitStatus()} returning the exit status code specified by the guest
 * application. However, the context is closed automatically. The hard exit can be customized using
 * {@link Builder#useSystemExit(boolean)}. If true, the context threads are unwound by
 * calling {@link System#exit(int)} with the exit status parameter specified by the guest
 * application. This operation terminates the whole host application.
 * 
 *
 * 
Pre-Initialization
 *
 * The context pre-initialization can be used to perform expensive builtin creation in the time of
 * native compilation.
 * 

 * The context pre-initialization is enabled by setting the system property
 * {@code polyglot.image-build-time.PreinitializeContexts} to a comma separated list of language ids
 * which should be pre-initialized, for example:
 * {@code -Dpolyglot.image-build-time.PreinitializeContexts=js,python}
 * 

 * See
 * {@code org.pkl.thirdparty.truffle.api.TruffleLanguage.patchContext(java.lang.Object, org.pkl.thirdparty.truffle.api.TruffleLanguage.Env)}
 * for details about pre-initialization for language implementers.
 *
 * @since 19.0
 */
public final class Context implements AutoCloseable {

    final AbstractContextDispatch dispatch;
    final Object receiver;
    final Context currentAPI;
    final Engine engine;

    @SuppressWarnings("unchecked")
     Context(AbstractContextDispatch dispatch, T receiver, Engine engine) {
        this.dispatch = dispatch;
        this.receiver = receiver;
        this.engine = engine;
        this.currentAPI = new Context(this);
        dispatch.setAPI(receiver, this);
    }

    private Context() {
        this.dispatch = null;
        this.receiver = null;
        this.engine = null;
        this.currentAPI = null;
    }

    private  Context(Context creatorAPI) {
        this.dispatch = creatorAPI.dispatch;
        this.receiver = creatorAPI.receiver;
        this.engine = creatorAPI.engine.currentAPI;
        this.currentAPI = null;
    }

    /**
     * Provides access to meta-data about the underlying Graal {@linkplain Engine engine}.
     *
     * @return Graal {@link Engine} being used by this context
     * @since 19.0
     */
    public Engine getEngine() {
        return engine;
    }

    /**
     * Evaluates a source object by using the {@linkplain Source#getLanguage() language} specified
     * in the source. The result is accessible as {@link Value value} and never returns
     * null. The first time a source is evaluated, it will be parsed. Consecutive
     * invocations of eval with the same source will only execute the already parsed code.
     * 

     * Basic Example:
     *
     * 
     * try (Context context = Context.create()) {
     *     Source source = Source.newBuilder("js", "42", "mysource.js").build();
     *     Value result = context.eval(source);
     *     assert result.asInt() == 42;
     * }
     * 
     *
     * @param source a source object to evaluate
     * @throws PolyglotException in case the guest language code parsing or evaluation failed.
     * @throws IllegalStateException if the context is already closed and the current thread is not
     *             allowed to access it.
     * @throws IllegalArgumentException if the language of the given source is not installed or the
     *             {@link Source#getMimeType() MIME type} is not supported with the language.
     * @return the evaluation result. The returned instance is never null, but the
     *         result might represent a {@link Value#isNull() null} value.
     * @since 19.0
     */
    public Value eval(Source source) {
        return dispatch.eval(receiver, source.getLanguage(), source);
    }

    /**
     * Evaluates a guest language code literal, using a provided {@link Language#getId() language
     * id}. The result is accessible as {@link Value value} and never returns null. The
     * provided {@link CharSequence} must represent an immutable String.
     * 

     * Basic Example:
     *
     * 
     * try (Context context = Context.create()) {
     *     Value result = context.eval("js", "42");
     *     assert result.asInt() == 42;
     * }
     * 
     *
     * @throws PolyglotException in case the guest language code parsing or evaluation failed.
     * @throws IllegalArgumentException if the language does not exist or is not accessible.
     * @throws IllegalStateException if the context is already closed and the current thread is not
     *             allowed to access it, or if the given language is not installed.
     * @return the evaluation result. The returned instance is never null, but the
     *         result might represent a {@link Value#isNull() null} value.
     * @since 19.0
     */
    public Value eval(String languageId, CharSequence source) {
        return eval(Source.create(languageId, source));
    }

    /**
     * Parses but does not evaluate a given source by using the {@linkplain Source#getLanguage()
     * language} specified in the source and returns a {@link Value value} that can be
     * {@link Value#execute(Object...) executed}. If a parsing fails, e.g. due to a syntax error in
     * the source, then a {@link PolyglotException} will be thrown. In case of a syntax error the
     * {@link PolyglotException#isSyntaxError()} will return true. There is no
     * guarantee that only syntax errors will be thrown by this method. Any other guest language
     * exception might be thrown. If the validation succeeds then the method completes without
     * throwing an exception.
     * 

     * The result value only supports an empty set of arguments to {@link Value#execute(Object...)
     * execute}. If executed repeatedly then the source is evaluated multiple times.
     * {@link Source.Builder#interactive(boolean) Interactive} sources will print their result for
     * each execution of the parsing result to the {@link Builder#out(OutputStream) output} stream.
     * 

     * If the parsing succeeds and the source is {@link Source.Builder#cached(boolean) cached} then
     * the result will automatically be reused for consecutive calls to {@link #parse(Source)} or
     * {@link #eval(Source)}. If the validation should be performed for each invocation or the
     * result should not be remembered then {@link Source.Builder#cached(boolean) cached} can be set
     * to false. By default sources are cached.
     * 

     * Basic Example:
     *
     * 
     * try (Context context = Context.create()) {
     *     Source source = Source.create("js", "42");
     *     Value value;
     *     try {
     *         value = context.parse(source);
     *         // parsing succeeded
     *     } catch (PolyglotException e) {
     *         if (e.isSyntaxError()) {
     *             SourceSection location = e.getSourceLocation();
     *             // syntax error detected at location
     *         } else {
     *             // other guest error detected
     *         }
     *         throw e;
     *     }
     *     // evaluate the parsed script
     *     value.execute();
     * }
     * 
     *
     * @param source a source object to parse
     * @throws PolyglotException in case the guest language code parsing or validation failed.
     * @throws IllegalArgumentException if the language does not exist or is not accessible.
     * @throws IllegalStateException if the context is already closed and the current thread is not
     *             allowed to access it, or if the given language is not installed.
     * @since 20.2
     */
    public Value parse(Source source) throws PolyglotException {
        return dispatch.parse(receiver, source.getLanguage(), source);
    }

    /**
     * Parses but does not evaluate a guest language code literal using a provided
     * {@link Language#getId() language id} and character sequence and returns a {@link Value value}
     * that can be {@link Value#execute(Object...) executed}. The provided {@link CharSequence} must
     * represent an immutable String. This method represents a short-hand for {@link #parse(Source)}
     * .
     * 

     * The result value only supports an empty set of arguments to {@link Value#execute(Object...)
     * execute}. If executed repeatedly then the source is evaluated multiple times.
     * {@link Source.Builder#interactive(boolean) Interactive} sources will print their result for
     * each execution of the parsing result to the {@link Builder#out(OutputStream) output} stream.
     * 

     *
     * 
     * try (Context context = Context.create()) {
     *     Value value;
     *     try {
     *         value = context.parse("js", "42");
     *         // parsing succeeded
     *     } catch (PolyglotException e) {
     *         if (e.isSyntaxError()) {
     *             SourceSection location = e.getSourceLocation();
     *             // syntax error detected at location
     *         } else {
     *             // other guest error detected
     *         }
     *         throw e;
     *     }
     *     // evaluate the parsed script
     *     value.execute();
     * }
     * 
     *
     * @throws PolyglotException in case the guest language code parsing or evaluation failed.
     * @throws IllegalArgumentException if the language does not exist or is not accessible.
     * @throws IllegalStateException if the context is already closed and the current thread is not
     *             allowed to access it, or if the given language is not installed.
     * @since 20.2
     */
    public Value parse(String languageId, CharSequence source) {
        return parse(Source.create(languageId, source));
    }

    /**
     * Returns polyglot bindings that may be used to exchange symbols between the host and guest
     * languages. All languages have unrestricted access to the polyglot bindings. The returned
     * bindings object always has {@link Value#hasMembers() members} and its members are
     * {@link Value#getMember(String) readable}, {@link Value#putMember(String, Object) writable}
     * and {@link Value#removeMember(String) removable}.
     * 

     * Guest languages may put and get members through language specific APIs. For example, in
     * JavaScript, symbols of the polyglot bindings can be accessed using
     * Polyglot.import("name") and set using
     * Polyglot.export("name", value). Please see the individual language reference on
     * how to access these symbols.
     *
     * @throws IllegalStateException if context is already closed.
     * @since 19.0
     */
    public Value getPolyglotBindings() {
        return dispatch.getPolyglotBindings(receiver);
    }

    /**
     * Returns a value that represents the top-most bindings of a language. The top most bindings of
     * the language returns a {@link Value#getMember(String) member} for a symbol in the scope.
     * Languages may allow modifications of members of the returned bindings object at the
     * language's discretion. If the language has not been {@link #initialize(String) initialized}
     * yet, it will be initialized when the bindings are requested.
     *
     * @throws IllegalArgumentException if the language does not exist or is not accessible.
     * @throws IllegalStateException if the context is already closed.
     * @throws PolyglotException in case the lazy initialization failed due to a guest language
     *             error.
     * @since 19.0
     */
    public Value getBindings(String languageId) {
        return dispatch.getBindings(receiver, languageId);
    }

    /**
     * Forces the initialization of a language. It is not necessary to explicitly initialize a
     * language, it will be initialized the first time it is used.
     *
     * @param languageId the identifier of the language to initialize.
     * @return true if the language was initialized. Returns false if it
     *         was already initialized.
     * @throws PolyglotException in case the initialization failed due to a guest language error.
     * @throws IllegalArgumentException if the language does not exist or is not accessible.
     * @throws IllegalStateException if the context is already closed.
     * @since 19.0
     */
    public boolean initialize(String languageId) {
        return dispatch.initializeLanguage(receiver, languageId);
    }

    /**
     * Resets all accumulators of resource limits for the associated context to zero.
     *
     * @since 19.3
     */
    public void resetLimits() {
        dispatch.resetLimits(receiver);
    }

    /**
     * Converts a host value to a polyglot {@link Value value} representation. This conversion is
     * applied implicitly whenever {@link Value#execute(Object...) execution} or
     * {@link Value#newInstance(Object...) instantiation} arguments are provided,
     * {@link Value#putMember(String, Object) members} and
     * {@link Value#setArrayElement(long, Object) array elements} are set or when a value is
     * returned by a {@link Proxy polyglot proxy}. It is not required nor efficient to explicitly
     * convert to polyglot values before performing these operations. This method is useful to
     * convert a {@link Value#as(Class) mapped} host value back to a polyglot value while preserving
     * the identity.
     * 

     * When a host value is converted to a polyglot value the following rules apply:
     * 

     * 
If the hostValue is null, then it will be interpreted as
     * polyglot {@link Value#isNull() null}.
     * 
If the hostValue is already a {@link Value polyglot value}, then it will be
     * cast to {@link Value}.
     * 
If the hostValue is an instance of {@link Byte}, {@link Short},
     * {@link Integer}, {@link Long}, {@link Float} or {@link Double}, then it will be interpreted
     * as polyglot {@link Value#isNumber() number}. Other subclasses of {@link Number} will be
     * interpreted as {@link Value#isHostObject() host object} (see later).
     * 
If the hostValue is an instance of {@link Character} or {@link String}, then
     * it will be interpreted as polyglot {@link Value#isString() string}.
     * 
If the hostValue is an instance of {@link Boolean}, then it will be
     * interpreted as polyglot {@link Value#isBoolean() boolean}.
     * 
If the hostValue is an instance of {@link Instant}, {@link LocalTime},
     * {@link ZonedDateTime}, {@link java.util.Date} but not {@link java.sql.Date} or
     * {@link java.sql.Time} then it will be interpreted as polyglot {@link Value#isTime() time}.
     * 
If the hostValue is an instance of {@link Instant}, {@link LocalDate},
     * {@link ZonedDateTime}, {@link java.util.Date} but not {@link java.sql.Time} or
     * {@link java.sql.Date} then it will be interpreted as polyglot {@link Value#isDate() date}.
     * 
If the hostValue is an instance of {@link ZoneId}, {@link Instant},
     * {@link ZonedDateTime}, {@link java.util.Date} but not {@link java.sql.Time} and
     * {@link java.sql.Date} then it will be interpreted as polyglot {@link Value#isTimeZone() time
     * zone}.
     * 
If the hostValue is an instance of {@link ZonedDateTime}, {@link Instant},
     * {@link ZonedDateTime}, {@link java.util.Date} but not {@link java.sql.Time} and
     * {@link java.sql.Date} then it will be interpreted as polyglot {@link Value#isInstant()
     * instant}.
     * 
If the hostValue is an instance of {@link Duration} then it will be
     * interpreted as polyglot {@link Value#isDuration() duration}.
     * 
If the hostValue is a {@link Proxy polyglot proxy}, then it will be
     * interpreted according to the behavior specified by the proxy. See the javadoc of the proxy
     * subclass for further details.
     * 
If the hostValue is a non-primitive {@link Value#as(Class) mapped Java
     * value}, then the original value will be restored. For example, if a guest language object was
     * mapped to {@link Map}, then the original object identity will be preserved when converting
     * back to a polyglot value.
     * 
Any other hostValue will be interpreted as {@link Value#isHostObject() host
     * object}. Host objects expose all their public java fields and methods as
     * {@link Value#getMember(String) members}. In addition, Java arrays, subtypes of {@link List}
     * and {@link Entry} will be interpreted as a value with {@link Value#hasArrayElements() array
     * elements}. The subtypes of {@link Iterable} will be interpreted as a value with
     * {@link Value#hasIterator()} iterator}. The subtypes of {@link Iterator} will be interpreted
     * as an {@link Value#isIterator() iterator} value. The subtypes of {@link Map} will be
     * interpreted as a value with {@link Value#hasHashEntries()} hash entries}. And single method
     * interfaces annotated with {@link FunctionalInterface} are {@link Value#execute(Object...)
     * executable} directly. Java {@link Class} instances are interpreted as
     * {@link Value#canInstantiate() instantiable}, but they do not expose Class methods as members.
     * 
     * 

     * Basic Examples:
     *
     * The following assertion statements always hold:
     *
     * 
     * Context context = Context.create();
     * assert context.asValue(null).isNull();
     * assert context.asValue(42).isNumber();
     * assert context.asValue("42").isString();
     * assert context.asValue('c').isString();
     * assert context.asValue(new String[0]).hasArrayElements();
     * assert context.asValue(new ArrayList<>()).isHostObject();
     * assert context.asValue(new ArrayList<>()).hasArrayElements();
     * assert context.asValue((Supplier) () -> 42).execute().asInt() == 42;
     * 
     *
     * 
Mapping to Java methods and fields
     *
     * When Java host objects are passed to guest languages, their public methods and fields are
     * provided as {@link Value#getMember(String) members}. Methods and fields are grouped by name,
     * so only one member is exposed for each name.
     * 

     * {@link Class} objects have a member named {@code static} referring to the class's companion
     * object containing the static methods of the class. Likewise, the companion object has a
     * member named {@code class} that points back to the class object.
     * 

     * When an argument value needs to be mapped to match a required Java method parameter type,
     * then the semantics of {@link Value#as(Class) host value mapping} is used. The result of the
     * mapping is equivalent of calling {@link Value#as(Class)} with the parameter type. Therefore,
     * a {@link ClassCastException} or {@link NullPointerException} is thrown if a parameter value
     * cannot be cast to the required parameter type.
     * 

     * Overloaded java methods are selected based on the provided arguments. In case multiple mapped
     * Java methods with the same name are applicable for {@link Value#execute(Object...)
     * executions} or {@link Value#newInstance(Object...) instantiations}, then the method with the
     * most concrete method with applicable arguments will be called.
     * 

     * The following parameter type hierarchy is used for a method resolution. Left-most parameter
     * types are prioritized over types to their right.
     * 

     * 
{@link Value#isBoolean() Boolean} values: boolean, Boolean, Object
     * 
String values: char, Character, String, CharSequence, Object
     * 
Number values: byte, Byte, short, Short, int, Integer, long, Long, float, Float, double,
     * Double, Number, Object
     * 
Other values are resolved based on their Java type hierarchy.
     * 
     * If there are multiple concrete methods or too many arguments provided, then an illegal
     * argument type error will be raised.
     * 

     * Advanced Example:
     *
     * This example first creates a new instance of the Java class Record and inspects
     * it using the polyglot value API. Later, a host value is converted to a polyglot value using
     * JavaScript guest language.
     * 

     * In the following examples all assertions hold.
     *
     * 
     * class JavaRecord {
     *   public int x = 42;
     *   public double y = 42.0;
     *   public String name() {
     *     return "foo";
     *   }
     * }
     * Context context = Context.create();
     * Value record = context.asValue(new JavaRecord());
     * assert record.getMember("x").asInt() == 42;
     * assert record.getMember("y").asDouble() == 42.0d;
     * assert record.getMember("name").execute().asString().equals("foo");
     *
     * assert context.eval("js", "(function(record) record.x)")
     *               .execute(record).asInt() == 42;
     * assert context.eval("js", "(function(record) record.y)")
     *               .execute(record).asDouble() == 42.0d;
     * assert context.eval("js", "(function(record) record.name())")
     *               .execute(record).asString().equals("foo");
     * 
     *
     * @see Value#as(Class)
     * @throws IllegalStateException if the context is already closed
     * @param hostValue the host value to convert to a polyglot value.
     * @return the polyglot value.
     * @since 19.0
     */
    public Value asValue(Object hostValue) {
        return dispatch.asValue(receiver, hostValue);
    }

    /**
     * Explicitly enters the context on the current thread. A context needs to be entered and left
     * for any operation to be performed. For example, before and after invoking the
     * {@link Value#execute(Object...) execute} method. This can be inefficient if a very high
     * number of simple operations needs to be performed. By {@link #enter() entering} and
     * {@link #leave() leaving} once explicitly, the overhead for entering/leaving the context for
     * each operation can be eliminated. Contexts can be entered multiple times on the same thread.
     *
     * @throws IllegalStateException if the context is already {@link #close() closed}.
     * @throws PolyglotException if a language has denied execution on the current thread.
     * @see #leave() leave a context.
     * @since 19.0
     */
    public void enter() {
        checkCreatorAccess("entered");
        dispatch.explicitEnter(receiver);
    }

    /**
     * {@inheritDoc}
     *
     * @since 19.0
     */
    @Override
    public boolean equals(Object obj) {
        if (obj instanceof Context) {
            Context other = ((Context) obj);
            return receiver.equals(other.receiver);
        }
        return false;
    }

    /**
     * {@inheritDoc}
     *
     * @since 19.0
     */
    @Override
    public int hashCode() {
        return Objects.hashCode(receiver);
    }

    /**
     * Explicitly leaves the context on the current thread. The context must be {@link #enter()
     * entered} before calling this method.
     *
     * @throws IllegalStateException if the context is already closed or if the context was not
     *             {@link #enter() entered} on the current thread.
     * @see #enter() enter a context.
     * @since 19.0
     */
    public void leave() {
        checkCreatorAccess("left");
        dispatch.explicitLeave(receiver);
    }

    private void checkCreatorAccess(String operation) {
        if (this.currentAPI == null) {
            throw new IllegalStateException(String.format("Context instances that were received using Context.get() cannot be %s.", operation));
        }
    }

    /**
     * Closes the context and frees up potentially allocated native resources. A context cannot free
     * all native resources allocated automatically. For this reason it is necessary to close
     * contexts after use. If a context is cancelled, then the executing thread will throw a
     * {@link PolyglotException}. The exception indicates that it was
     * {@link PolyglotException#isCancelled() cancelled}. Please note, canceling a single context
     * can negatively affect the performance of other executing contexts constructed with the same
     * engine.
     * 

     * If internal errors occur during context closing, then they are printed to the configured
     * {@link Builder#err(OutputStream) error output stream}. If a context was closed, then its
     * methods will throw an {@link IllegalStateException} when invoked. If an attempt to close a
     * context was successful, then consecutive calls to close have no effect.
     * 

     * For convenience, before the actual closing process begins, the close method leaves the
     * context on the current thread, if it was entered {@link #enter() explicitly}.
     *
     * @param cancelIfExecuting if true then currently executing contexts will be
     *            {@link PolyglotException#isCancelled() cancelled}, else an
     *            {@link IllegalStateException} is thrown.
     * @see Engine#close() close an engine.
     * @throws PolyglotException in case the close failed due to a guest language error, or, if
     *             cancelIfExecuting is false, the exception is also thrown when the
     *             context was {@link PolyglotException#isCancelled() cancelled} or the context was
     *             {@link PolyglotException#isExit() exited} at request of the guest application.
     * @throws IllegalStateException if the context is still running and cancelIfExecuting is
     *             false
     * @since 19.0
     */
    public void close(boolean cancelIfExecuting) {
        checkCreatorAccess("closed");
        dispatch.close(receiver, cancelIfExecuting);
    }

    /**
     * Closes this context and frees up potentially allocated native resources. A context may not
     * free all native resources allocated automatically. For this reason it is recommended to close
     * contexts after use. If the context is currently being executed on another thread, then an
     * {@link IllegalStateException} is thrown. To close concurrently executing contexts see
     * {@link #close(boolean)}.
     * 

     * If internal errors occur during the context closure, then they are printed to the configured
     * {@link Builder#err(OutputStream) error output stream}. If a context was closed, then its
     * methods will throw an {@link IllegalStateException}, when invoked. If an attempt to close a
     * context was successful, then consecutive calls to close have no effect.
     * 

     * For convenience, before the actual closing process begins, the close method leaves the
     * context on the current thread, if it was entered {@link #enter() explicitly}.
     *
     * @throws PolyglotException in case the close failed due to a guest language error, or the
     *             context was {@link PolyglotException#isCancelled() cancelled} or the context was
     *             {@link PolyglotException#isExit() exited} at request of the guest application.
     * @throws IllegalStateException if the context is currently executing on another thread.
     * @see Engine#close() close an engine.
     * @since 19.0
     */
    public void close() {
        close(false);
    }

    /**
     * Use this method to interrupt this context. The interruption is non-destructive meaning the
     * context is still usable after this method finishes. Please note that guest finally blocks are
     * executed during interrupt. A context thread may not be interruptiple if it uses
     * non-interruptible waiting or executes non-interruptible host code.
     *
     * This method may be used as a "soft cancel", meaning that it can be used before
     * {@link #close(boolean) close(true)} is executed.
     *
     * @param timeout specifies the duration the interrupt method will wait for the active threads
     *            of the context to be finished. Setting the duration to {@link Duration#ZERO 0}
     *            means wait indefinitely.
     * @throws IllegalStateException in case the context is entered in the current thread.
     * @throws TimeoutException in case the interrupt was not successful, i.e., not all threads were
     *             finished within the specified time limit.
     *
     * @since 20.3
     */
    public void interrupt(Duration timeout) throws TimeoutException {
        checkCreatorAccess("interrupted");
        if (!dispatch.interrupt(receiver, timeout)) {
            throw new TimeoutException("Interrupt timed out.");
        }
    }

    /**
     * Polls safepoints events and executes them for the current thread. This allows guest languages
     * to run actions between long running host method calls. Polyglot embeddings that rely on
     * cancellation should call this method whenev a potentially long running host operation is
     * executed. For example, iterating an unbounded array. Guest language code and operations
     * automatically poll safepoints regularly.
     *
     * 

     * In this example we allow {@link Context#interrupt(Duration) interruption} and
     * {@link Context#close(boolean) cancellation} to stop the processing of our event queue.
     *
     * 
     * class EventProcessor {
     *
     *   List