Class TruffleStackTrace

java.lang.Object
java.lang.Throwable
java.lang.Exception
com.oracle.truffle.api.TruffleStackTrace
All Implemented Interfaces:
Serializable
public final class TruffleStackTrace extends Exception
Represents a guest language stack trace. A TruffleStackTrace is automatically added when a Throwable passes through a call target. ControlFlowException and PolyglotException do not get a TruffleStackTrace. An internal or host Throwable is added a TruffleStackTrace, as long as suppression is not disabled for this throwable, via a Throwable added to the list of suppressed exceptions.

A guest language stack trace element is automatically added by the Truffle runtime every time the Throwable passes through a call target. This is incremental and therefore efficient if the exception is later caught in the same compilation unit.

Note that if the Throwable is caught, its stack trace should be filled eagerly with fillIn(Throwable), unless it can be guaranteed to be re-thrown in the same call target, or that the stack trace will not be used.

See getStackTrace(Throwable) to retrieve the guest language stack trace from a Throwable.

Since:
19.0
See Also:

  • Method Details

    • fillInStackTrace

      public Throwable fillInStackTrace()
      Overrides:
      fillInStackTrace in class Throwable
      Since:
      19.0

    • toString

      public String toString()
      Overrides:
      toString in class Throwable
      Since:
      19.0

    • getStackTrace

      public static List<TruffleStackTraceElement> getStackTrace(Throwable throwable)
      Returns the guest language frames that are stored in this throwable or null if no guest language frames can ever be stored in this throwable. This method fills in the stacktrace by calling fillIn(Throwable), so it is not necessary to call fillIn(Throwable) before. The returned list is not modifiable. The number of stack trace elements that are filled in can be customized by the stackTraceElementLimit parameter of the AbstractTruffleException constructor.
      Parameters:
      throwable - the Throwable instance to look for guest language frames
      Throws:
      NullPointerException - if the Throwable is null
      Since:
      19.0

    • getAsynchronousStackTrace

      public static List<TruffleStackTraceElement> getAsynchronousStackTrace(CallTarget target, Frame frame)
      Returns asynchronous guest language stack frames that led to the execution of given CallTarget on the given Frame. Returns null if no asynchronous stack is known. Call this with a context entered only.

      Languages might not provide asynchronous stack frames by default for performance reasons. Instruments might need to instruct languages to provide the asynchronous stacks.

      Returns:
      a list of asynchronous frames, or null.
      Since:
      20.1.0

    • fillIn

      public static TruffleStackTrace fillIn(Throwable throwable)
      Fills in the guest language stack frames from the current frames on the stack. If the stack was already filled before then this method has no effect. The number stack trace elements that are filled in can be customized by the stackTraceElementLimit parameter of the AbstractTruffleException constructor. The implementation attaches a lightweight exception object as a suppressed exception to internal and host (but not guest) exceptions.
      Parameters:
      throwable - the Throwable to fill
      Throws:
      NullPointerException - if the Throwable is null
      Since:
      19.0