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:
```
final class MyNode extends Node {
    void executeInContext(TruffleLanguage.Env env) {
        MyContext outerLangContext = getContext();

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

            assert outerLangContext != innerLangContext;
        } finally {
            innerContext.leave(this, 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.

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Closes this context and disposes its resources.
`void`	`closeCancelled(Node closeLocation, String message)` Force closes the context as cancelled and stops all the execution on all active threads using a `ThreadDeath` exception.
`void`	`closeResourceExhausted(Node location, String message)` Force closes the context due to resource exhaustion.
`Object`	`enter(Node node)` Enters this context and returns an object representing the previous context.
`boolean`	`equals(Object obj)`
`TruffleContext`	`getParent()` Get a parent context of this context, if any.
`int`	`hashCode()`
`boolean`	`isActive()` Returns `true` if the context is currently active on the current thread, else `false`.
`boolean`	`isCancelling()` Returns `true` if the context is being cancelled else `false`.
`boolean`	`isClosed()` Returns `true` if the context was closed else `false`.
`boolean`	`isEntered()` Checks whether the context is entered on the current thread and the context is the currently active context on this thread.
`void`	`leave(Node node, Object prev)` Leaves this context and sets the previous context as the new current context.
`<T> T`	`leaveAndEnter(Node node, Supplier<T> runWhileOutsideContext)` Leaves this context, runs the passed supplier and reenters the context.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
    
    Since:
    
    20.3
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
    
    Since:
    
    20.3
  - 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(Node node)
```
    Enters this context and returns an object representing the previous context. Calls to enter must be followed by a call to TruffleContext.leave(Node, 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(Node, Object). The result value must not be stored permanently.
    An adopted node may be passed to allow perform optimizations on the fast-path. If a null node is passed then entering a context will result in a boundary call in compiled code. If the provided node is not adopted an IllegalArgumentException is thrown.
    Entering a language context is designed for compilation and is most efficient if the context instance is compilation final.
    Example usage:
```
final class MyNode extends Node {
    void executeInContext(TruffleLanguage.Env env) {
        MyContext outerLangContext = getContext();

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

            assert outerLangContext != innerLangContext;
        } finally {
            innerContext.leave(this, p);
        }
        assert outerLangContext == getContext();
        innerContext.close();
    }
}
private static MyContext getContext() {
    return TruffleLanguage.getCurrentContext(MyLanguage.class);
}
```
    Since:
    
    20.3
    
    See Also:
    
    TruffleContext.leave(Node, Object)
  - isEntered
```
public boolean isEntered()
```
    Checks whether the context is entered on the current thread and the context is the currently active context on this thread. There can be multiple contexts active on a single thread, but this method only returns true if it is the top-most context. This method is thread-safe and may be used from multiple threads.
    
    Returns:
    
    true if the context is active, false otherwise
    
    Since:
    
    20.0
  - isActive
```
public boolean isActive()
```
    Returns true if the context is currently active on the current thread, else false. Checks whether the context has been previously entered by this thread with TruffleContext.enter(Node) and hasn't been left yet with TruffleContext.leave(Node, java.lang.Object) methods. Multiple contexts can be active on a single thread. See TruffleContext.isEntered() for checking whether it is the top-most entered context. This method is thread-safe and may be used from multiple threads.
    
    Since:
    
    20.3
  - isClosed
```
public boolean isClosed()
```
    Returns true if the context was closed else false. A context may be closed if TruffleContext.close() or TruffleContext.closeCancelled(Node, String) was called previously.
    
    Since:
    
    20.3
  - isCancelling
```
public boolean isCancelling()
```
    Returns true if the context is being cancelled else false. A context may be in the process of cancelling if TruffleContext.closeCancelled(Node, String) was called previously.
    
    Since:
    
    21.1
  - leave
```
public void leave(Node node,
                  Object prev)
```
    Leaves this context and sets the previous context as the new current context.
    An adopted node may be passed to allow perform optimizations on the fast-path. If a null node is passed then entering a context will result in a boundary call in compiled code. If the node is not adopted an IllegalArgumentException is thrown.
    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(Node)
    
    Since:
    
    20.3
    
    See Also:
    
    TruffleContext.enter(Node)
  - leaveAndEnter
```
public <T> T leaveAndEnter(Node node,
                           Supplier<T> runWhileOutsideContext)
```
    Leaves this context, runs the passed supplier and reenters the context. This is useful when the current thread must wait for another thread (and does not need to access the context to do so) and triggering multithreading is not desired, for instance when implementing coroutines with threads. The supplier cannot access the context and must not run any guest language code or invoke interoperability messages.
    The supplier will typically notify another thread that it can now enter the context without triggering multithreading and then wait for some thread to leave the context before exiting the supplier and reentering the context (again to avoid triggering multithreading).
    An adopted node may be passed to allow perform optimizations on the fast-path. If a null node is passed then entering a context will result in a boundary call in compiled code. If the provided node is not adopted an IllegalArgumentException is thrown.
    Entering a language context is designed for compilation and is most efficient if the context instance is compilation final.
    
    Parameters:
    
    node - an adopted node or null
    
    runWhileOutsideContext - the supplier to run while having left this context
    
    Since:
    
    21.1
  - close
```
public void close()
```
    Closes this context and disposes its resources. Closes this context and disposes its resources. A context cannot be closed if it is currently entered or active 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.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Throws:
    
    UnsupportedOperationException - if the close operation is not supported on this context
    
    IllegalStateException - if the context is active.
    
    Since:
    
    0.27
    
    See Also:
    
    TruffleContext.closeCancelled(Node, String), TruffleContext.closeResourceExhausted(Node, String)
  - closeCancelled
```
public void closeCancelled(Node closeLocation,
                           String message)
```
    Force closes the context as cancelled and stops all the execution on all active threads using a ThreadDeath exception. If this context is not currently entered on the current thread then this method waits until the close operation is complete and TruffleContext.isClosed() returns true, else it throws the cancelled exception upon its completion of this method. If an attempt to close a context was successful then consecutive calls to close have no effect.
    If forced and this context currently entered on the current thread and no other context is entered on the current thread then this method directly throws a ThreadDeath error instead of completing to indicate that the current thread should be stopped. The thrown ThreadDeath must not be caught by the guest language and freely propagated to the guest application to cancel the execution on the current thread. If a context is active on the current thread, but not entered, then an IllegalStateException is thrown, as parent contexts that are active on the current thread cannot be cancelled.
    
    Parameters:
    
    closeLocation - the node where the close occurred. If the context is currently entered on the thread, then this node will be used as location, for the exception thrown. If the context is not entered, then the closeLocation parameter will be ignored.
    
    message - exception text for humans provided to the embedder and tools that observe the cancellation.
    
    Throws:
    
    UnsupportedOperationException - if the close operation is not supported on this context
    
    IllegalStateException - if the context is active but not entered on the current thread.
    
    Since:
    
    20.3
    
    See Also:
    
    TruffleContext.close(), TruffleContext.closeResourceExhausted(Node, String)
  - closeResourceExhausted
```
public void closeResourceExhausted(Node location,
                                   String message)
```
    Force closes the context due to resource exhaustion. This method is equivalent to calling closeCancelled(location, message) except in addition the thrown PolyglotException returns true for PolyglotException.isResourceExhausted().
    
    Since:
    
    20.3
    
    See Also:
    
    PolyglotException.isResourceExhausted(), TruffleContext.close(), TruffleContext.closeCancelled(Node, String)

Class TruffleContext

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

equals

hashCode

getParent

enter

isEntered

isActive

isClosed

isCancelling

leave

leaveAndEnter

close

closeCancelled

closeResourceExhausted