TruffleSafepoint (GraalVM Truffle Java API Reference)

java.lang.Object
- com.oracle.truffle.api.TruffleSafepoint

```
public abstract class TruffleSafepoint
extends Object
```
Truffle safepoints allow interrupting the guest language execution to execute thread-local actions submitted by a language or tool. A safepoint is a location during the guest language execution where the state is consistent, and other operations can read its state.

Supporting Safepoints in a Language

Safepoints are explicitly polled by invoking the TruffleSafepoint.poll(Node) method. Safepoints are polled with relaxed location or with exact location. A poll with a relaxed location is significantly more efficient than a poll with a precise location as the compiler is able to move and combine the poll requests during compilation. A Truffle guest language implementation must ensure that a safepoint is polled repeatedly within a constant time interval. For example, a single arithmetic expression completes within a constant number of CPU cycles. However, a loop that summarizes values over an array uses a non-constant time dependent on the array size. This typically means that safepoints are best polled at the end of loops and at the end of function or method calls to cover recursion. In addition, any guest language code that blocks the execution, like guest language locks, need to use the blocking API to allow polling of safepoints while the thread is waiting.
Truffle's loop node and root node support safepoint polling automatically. No further calls to TruffleSafepoint.poll(Node) are therefore necessary. Custom loops or loops behind boundary annotated method calls are expected to be notified by the guest language implementation manually.
Thread local actions optionally incur side-effects. By default side-effects are enabled. A language implementation may disable side-effects temporarily for the current thread using TruffleSafepoint.setAllowSideEffects(boolean) method.

Submitting thread local actions

See ThreadLocalAction for details on how to submit actions.
Further information can be found in the safepoint tutorial.

Since:

21.1

See Also:

ThreadLocalAction, Context.safepoint()

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`TruffleSafepoint.CompiledInterruptible<T>` Just like `TruffleSafepoint.Interruptible` but allows partial evaluation.
`static interface`	`TruffleSafepoint.CompiledInterruptibleFunction<T,R>` Just like `TruffleSafepoint.InterruptibleFunction` but allows partial evaluation.
`static interface`	`TruffleSafepoint.Interrupter` An interrupter allows a foreign thread to interrupt the execution on a separate thread.
`static interface`	`TruffleSafepoint.Interruptible<T>` Function interface that represent interruptable Java methods.
`static interface`	`TruffleSafepoint.InterruptibleFunction<T,R>` Function interface that represent interruptable Java methods.

Constructor Summary

Constructors
Modifier Constructor and Description

protected TruffleSafepoint(com.oracle.truffle.api.impl.Accessor.EngineSupport support)
Do not extend this class.

Constructors
Modifier	Constructor and Description
`protected`	`TruffleSafepoint(com.oracle.truffle.api.impl.Accessor.EngineSupport support)` Do not extend this class.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static TruffleSafepoint`	`getCurrent()` Returns the current safepoint configuration for the current thread.
`abstract boolean`	`hasPendingSideEffectingActions()` Returns whether there is any pending side-effecting thread local action on this thread, due to being in a critical section using `TruffleSafepoint.setAllowSideEffects(boolean)`.
`static void`	`poll(Node location)` Polls a safepoint at the provided location.
`static void`	`pollHere(Node location)` Similar to `TruffleSafepoint.poll(Node)` but with exact location.
`abstract boolean`	`setAllowActions(boolean enabled)` Allows to temporarily delay all thread local actions on the current thread.
`abstract boolean`	`setAllowSideEffects(boolean enabled)` Allows to temporarily delay side-effecting thread local actions on the current thread.
`abstract <T> void`	`setBlocked(Node location, TruffleSafepoint.Interrupter interrupter, TruffleSafepoint.Interruptible<T> interruptible, T object, Runnable beforeInterrupt, Consumer<Throwable> afterInterrupt)` The same as `TruffleSafepoint.setBlockedFunction(Node, Interrupter, InterruptibleFunction, Object, Runnable, Consumer)`.
`abstract <T,R> R`	`setBlockedFunction(Node location, TruffleSafepoint.Interrupter interrupter, TruffleSafepoint.InterruptibleFunction<T,R> interruptible, T object, Runnable beforeInterrupt, Consumer<Throwable> afterInterrupt)` Transitions the current thread into a blocked state and calls an interruptible functional method.
`static <T> void`	`setBlockedThreadInterruptible(Node location, TruffleSafepoint.Interruptible<T> interruptible, T object)` Short-cut method to allow setting the blocked status for methods that throw `InterruptedException` and support interrupting using `Thread.interrupt()`.
`static <T,R> R`	`setBlockedThreadInterruptibleFunction(Node location, TruffleSafepoint.InterruptibleFunction<T,R> interruptible, T object)` Short-cut method to allow setting the blocked status for methods that throw `InterruptedException` and support interrupting using `Thread.interrupt()`.

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

Constructor Detail
- TruffleSafepoint
```
protected TruffleSafepoint(com.oracle.truffle.api.impl.Accessor.EngineSupport support)
```
  Do not extend this class. This class is intended to be implemented by a Truffle runtime implementation.
  
  Since:
  
  21.1

Method Detail

poll
```
public static void poll(Node location)
```
Polls a safepoint at the provided location. This allows to run thread local actions at this location. A Truffle guest language implementation must ensure that a safepoint is polled repeatedly within a constant time interval. See TruffleSafepoint for further details.
In compiled code calls to this method are removed. Instead the compiler inserts safepoints automatically at loop ends and method exits. In this case the node location is approximated by frame state of method ends and loop exits in the compiler IR. For method ends the parent root node and for loop exits the loop node is passed as location.
Guest language exceptions may be thrown by this method. If side-effects are allowed then also guest language exceptions may be thrown. Otherwise only internal or thread-death exceptions may be thrown. This method is safe to be used on compiled code paths.
Example usage with an unbounded loop sum behind a CompilerDirectives.TruffleBoundary.
```
 @TruffleBoundary
 int sum(int[] array) {
     int sum = 0;
     for (int i = 0; i < array.length; i++) {
         sum += array[i];

         TruffleSafepoint.poll();
     }
     return sum;
 }
 
```
Parameters:

location - the location of the poll. Must not be null.

Since:

21.1

See Also:

TruffleSafepoint, TruffleSafepoint.pollHere(Node)

pollHere
```
public static void pollHere(Node location)
```
Similar to TruffleSafepoint.poll(Node) but with exact location. A poll with relaxed location is significantly more efficient than a poll with precise location as the compiler is able to move and combine the poll requests during compilation. This method is safe to be used on compiled code paths.
Usage example:
```
 TruffleSafepoint safepoint = TruffleSafepoint.getCurrent();
 boolean prev = safepoint.setAllowSideEffects(false);
 try {
     // criticial section
 } finally {
     safepoint.setAllowSideEffects(prev);
     TruffleSafepoint.pollHere(this);
 }
 
```
Parameters:

location - the location of the poll. Must not be null.

Since:

21.1

See Also:

TruffleSafepoint.poll(Node)

setBlockedFunction

public abstract <T,R> R setBlockedFunction(Node location,
                                           TruffleSafepoint.Interrupter interrupter,
                                           TruffleSafepoint.InterruptibleFunction<T,R> interruptible,
                                           T object,
                                           Runnable beforeInterrupt,
                                           Consumer<Throwable> afterInterrupt)

Transitions the current thread into a blocked state and calls an interruptible functional method. The blocked state is restored when the interruptible method returns. Setting the blocked state allows safepoint notification while the current thread is blocked. This allows Truffle to interrupt e.g. locks temporarily to perform a thread local action.

The location> parameter is used poll all pending thread local actions before transition to blocked state.

The interrupter parameter specifies how the blocked state can be interrupted from another thread. The interrupter allows to interrupt the blocked state from other threads. For most blocking java.util.concurrent primitives the thread interrupter can be used. If the thread will be blocked in native code, other ways of interrupting, like signals may be used by implementing the TruffleSafepoint.Interrupter interface.

The interruptible parameter provides the method that calls the blocking method which throws InterruptedException on interrupt. In order to avoid allocations of the functional interface a single argument can be provided that is passed to the interface. This is typically the lock or semaphore instance. The implementation of this method is expected to throw an InterruptedException if the TruffleSafepoint.Interrupter.interrupt(Thread) method is invoked for this thread. For most java.util.concurrent primitives this is supported by using the interruptible blocking method variant, for example Lock.lockInterruptibly().

boundary is applied for the entire interruptible method call by default. If the interruptible is called from a compiled code path and the interruptible should get partial evaluated, then TruffleSafepoint.CompiledInterruptibleFunction should be used instead of TruffleSafepoint.InterruptibleFunction. In this case the parameter must be a partial evaluation constant.

The beforeInterrupt runnable and afterInterrupt consumer optional parameters allow to run code before and after a thread got interrupted and safepoint events are processed. If null is provided then no action will be performed. Arbitrary code may be executed in this runnable. Note that the blocked state is temporarily reset to its previous state while the afterInterrupt is called.

If an exception is thrown during the processing of the safepoint, afterInterrupt will receive the throwable as argument, or null if the safepoint successfully completed. This exception will still be thrown after completion of afterInterrupt, unless afterInterrupt throws an exception of its own.

Multiple recursive invocations of this method is supported. The previous blocked state will be restored when the method completes or fails.

Example usage:

Note there is a short-cut method to achieve the same behavior as in this example TruffleSafepoint.setBlockedThreadInterruptibleFunction(Node, InterruptibleFunction, Object).

 Queue

Class TruffleSafepoint

Supporting Safepoints in a Language

Submitting thread local actions

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TruffleSafepoint

Method Detail

poll

pollHere

setBlockedFunction

setBlocked

setBlockedThreadInterruptible

setBlockedThreadInterruptibleFunction

setAllowActions

setAllowSideEffects

hasPendingSideEffectingActions

getCurrent