Package org.graalvm.tools.lsp.server

Interface ContextAwareExecutor

public interface ContextAwareExecutor

This service interface defines methods to submit a task, i.e. a Callable, which will be executed in a Polyglot-Context-entered Thread to access features of the Truffle API.

Method Summary

Modifier and Type	Method	Description
<T> Future<T>	executeWithDefaultContext(Callable<T> taskWithResult)	Execute a task in a default Polyglot Context.
default <T> Future<T>	executeWithNestedContext(Callable<T> taskWithResult)	Execute a task in a newly created Polyglot Context.
<T> Future<T>	executeWithNestedContext(Callable<T> taskWithResult, boolean cached)	Same as executeWithNestedContext(Callable), but allowing to reuse nested Context instances.
<T> Future<T>	executeWithNestedContext(Callable<T> taskWithResult, int timeoutMillis, Callable<T> onTimeoutTask)	Same as executeWithNestedContext(Callable), but allowing the definition of a timeout and an onTimeoutTask for the execution.
void	resetContextCache()	Explicitly closes and removes all cached nested Context instances.
void	shutdown()	Shutdown this executor without waiting for tasks to finish.

Method Details

executeWithDefaultContext

<T> Future<T> executeWithDefaultContext(Callable<T> taskWithResult)

Execute a task in a default Polyglot Context. Use this method to access the Truffle API to parse source code or do language specific look-ups. To execute source code, use executeWithNestedContext(Callable).

Parameters:

taskWithResult - a task which shall be executed in a Polyglot-Context-entered Thread

Returns:

a Future to await the task's result

executeWithNestedContext

default <T> Future<T> executeWithNestedContext(Callable<T> taskWithResult)

Execute a task in a newly created Polyglot Context. This is useful if the task executes arbitrary source code which will change the state of the language contexts. The created Polyglot Context will be closed and removed afterwards. Remember, that creating new Polyglot Contexts might be expensive, depending on the installed languages.

Parameters:

taskWithResult - a task which shall be executed in a Polyglot-Context-entered Thread, which might have unwanted side-effects

Returns:

a Future to await the task's result

executeWithNestedContext

<T> Future<T> executeWithNestedContext(Callable<T> taskWithResult,
 boolean cached)

Same as executeWithNestedContext(Callable), but allowing to reuse nested Context instances.

Parameters:

taskWithResult - a task which shall be executed in a Polyglot-Context-entered Thread, which might have unwanted side-effects

cached - As creating new Polyglot Context instances might be expensive, this parameter allows to reuse the last nested Context instance for this call. To enforce using a fresh Context instance, resetContextCache() can be called.

Returns:

a Future to await the task's result

executeWithNestedContext

<T> Future<T> executeWithNestedContext(Callable<T> taskWithResult,
 int timeoutMillis,
 Callable<T> onTimeoutTask)

Same as executeWithNestedContext(Callable), but allowing the definition of a timeout and an onTimeoutTask for the execution.

Parameters:

taskWithResult - a task which shall be executed in a Polyglot-Context-entered Thread, which might have unwanted side-effects

timeoutMillis - time in milliseconds that taskWithResult is allowed to run.

onTimeoutTask - a task which is executed if the timeout is triggered.

Returns:

a Future to await the task's result, or the onTimeoutTask's result if the timeout triggered.

resetContextCache

void resetContextCache()

Explicitly closes and removes all cached nested Context instances.

shutdown

void shutdown()

Shutdown this executor without waiting for tasks to finish.