Package com.oracle.truffle.api

Class ThreadLocalAction

java.lang.Object
com.oracle.truffle.api.ThreadLocalAction
public abstract class ThreadLocalAction extends Object
Represents an action that is executed at a safepoint location of the guest language execution. Thread local actions can be submitted by languages or instruments. When an action is submitted it will be performed locally on the threads they are submitted to. After submitting a thread local action a Future is returned that allows to wait for and cancel the submitted action.

Thread local actions can be configured to allow side-effects using the constructor of the action. If side-effects are allowed (true), then the thread-local action is allowed to throw non-internal guest language exceptions from the action and modify the observable guest application state. Otherwise, the action is not allowed to modify the observable state, and any non-internal guest language exception will be transformed to an internal error of type AssertionError. Side-effects may be temporarily disabled by the guest language.

Thread local actions can also be set to be executed in a synchronous or asynchronous way. A submitted synchronous thread-local action waits until it is started on all threads that it was submitted on. Then the action is performed on all threads. After they were performed on a thread, the action waits for all threads to complete. No synchronous thread-local actions can be submitted while performing synchronous actions, as this may lead to deadlocks. If a synchronous event is submitted during a synchronous event, then a IllegalStateException is thrown when the action is submitted. Asynchronous thread-local actions might start and complete to perform independently of each other. There is no restriction on how they may be submitted.

Thread local actions are guaranteed to be executed in the same order as they were submitted for a context. If a context has pending thread-local actions, the actions may be canceled when the context is canceled or closed invalid. Exceptions thrown by the action will be forwarded handled by the guest language implementation. The only exception is for truffle exceptions that are thrown for non-side-effecting events.

Example Usage: 

 Env env; // language or instrument environment

 env.submitThreadLocal(null, new ThreadLocalAction(true, true) {
     @Override
     protected void perform(Access access) {
         assert access.getThread() == Thread.currentThread();
     }

     @Override
     protected String name() {
        return "MyAction"
     }

 });

Further information can be found in the safepoint tutorial.

Since:
21.1
See Also:

  • Constructor Details

    • ThreadLocalAction

      protected ThreadLocalAction(boolean hasSideEffects, boolean synchronous)
      Creates a new thread local action.
      Parameters:
      hasSideEffects - true if the event may have side-effects else false.
      synchronous - true if the event should run synchronous else the event will run asynchronous.
      Since:
      21.1
      See Also:

    • ThreadLocalAction

      protected ThreadLocalAction(boolean hasSideEffects, boolean synchronous, boolean recurring)
      Creates a new thread local action.
      Parameters:
      hasSideEffects - true if the event may have side-effects else false.
      synchronous - true if the event should run synchronous else the event will run asynchronous.
      recurring - true if the event should be rescheduled until cancelled, else false.
      Since:
      21.1
      See Also:

  • Method Details

    • perform

      protected abstract void perform(ThreadLocalAction.Access access)
      Performs the thread local action on a given thread.
      Parameters:
      access - allows access to the current thread, the code location and whether a context was active while executing the event.
      Since:
      21.1
      See Also: