com.oracle.truffle.api

Class TruffleContext

java.lang.Object

com.oracle.truffle.api.TruffleContext

All Implemented Interfaces:

AutoCloseable

public final class TruffleContext
extends Object
implements AutoCloseable

A handle on a context of a set of Truffle languages. This context handle is designed to be used by Truffle guest language implementations. The Truffle context can be used to create inner contexts for isolated execution of guest language code.

A context consists of a language context instance for each installed language. The current language context is created eagerly and can be accessed using a context reference or statically with TruffleLanguage.getCurrentContext(Class) after the context was entered.

The configuration for each language context is inherited from its parent/creator context. In addition to that config parameters can be passed to new language context instance of the current language. The configuration of other installed languages cannot be modified. To run guest language code in a context, the context needs to be first entered and then left. The context should be closed when it is no longer needed. If the context is not closed explicitly, then it is automatically closed together with the parent context.

Example usage:

void executeInContext(TruffleLanguage.Env env) {
    MyContext outerLangContext = getContext();

    TruffleContext innerContext = env.newContextBuilder().build();
    Object p = innerContext.enter();
    try {
        MyContext innerLangContext = getContext();

        assert outerLangContext != innerLangContext;
    } finally {
        innerContext.leave(p);
    }
    assert outerLangContext == getContext();
    innerContext.close();
}
private static MyContext getContext() {
    return TruffleLanguage.getCurrentContext(MyLanguage.class);
}

Since:

0.27

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	TruffleContext.Builder Builder class to create new TruffleContext instances.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this context and disposes its resources.
Object	enter() Enters this context and returns an object representing the previous context.
TruffleContext	getParent() Get a parent context of this context, if any.
boolean	isEntered() Checks whether the context is entered.
void	leave(Object prev) Leaves this context and sets the previous context as the new current context.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getParent

public TruffleContext getParent()

Get a parent context of this context, if any. This provides the hierarchy of inner contexts.

Returns:

a parent context, or null if there is no parent

Since:

0.30

enter

public Object enter()

Enters this context and returns an object representing the previous context. Calls to enter must be followed by a call to TruffleContext.leave(Object) in a finally block and the previous context must be passed as an argument. It is allowed to enter a context multiple times from the same thread. If the context is currently not entered by any thread then it is allowed be entered by an arbitrary thread. Entering the context from two or more different threads at the same time is possible, unless one of the loaded languages denies access to the thread, in which case an IllegalStateException is thrown. The result of the enter function is unspecified and must only be passed to TruffleContext.leave(Object). The result value must not be stored permanently.

Entering a language context is designed for compilation and is most efficient if the context instance is compilation final.

Example usage:

void executeInContext(TruffleLanguage.Env env) {
    MyContext outerLangContext = getContext();

    TruffleContext innerContext = env.newContextBuilder().build();
    Object p = innerContext.enter();
    try {
        MyContext innerLangContext = getContext();

        assert outerLangContext != innerLangContext;
    } finally {
        innerContext.leave(p);
    }
    assert outerLangContext == getContext();
    innerContext.close();
}
private static MyContext getContext() {
    return TruffleLanguage.getCurrentContext(MyLanguage.class);
}

Since:

0.27

See Also:

TruffleContext.leave(Object)

leave

public void leave(Object prev)

Leaves this context and sets the previous context as the new current context.

Leaving a language context is designed for compilation and is most efficient if the context instance is compilation final.

Parameters:

prev - the previous context returned by TruffleContext.enter()

Since:

0.27

See Also:

TruffleContext.enter()

close

public void close()

Closes this context and disposes its resources. A context cannot be closed if it is currently entered by any thread. If a closed context is attempted to be accessed or entered, then an IllegalStateException is thrown. If the context is not closed explicitly, then it is automatically closed together with the parent context. If an attempt to close a context was successful then consecutive calls to close have no effect.

Only contexts created by TruffleContext.Builder.build() can be explicitly closed. Other instances throw UnsupportedOperationException on close attempts.

Specified by:

close in interface AutoCloseable

Throws:

UnsupportedOperationException - when not created by TruffleContext.Builder.build().

Since:

0.27

isEntered

public boolean isEntered()

Checks whether the context is entered. Checks whether the context has been previously entered by this thread with TruffleContext.enter() and hasn't been left yet with TruffleContext.leave(java.lang.Object) methods. This method is thread-safe and may be used from multiple threads.

Returns:

true if the context is active, false otherwise

Since:

20.0.0