com.oracle.truffle.api

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 TruffleStackTrace.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.

Since:

19.0

See Also:

getStackTrace(Throwable) to retrieve the guest language stack trace from a {@link Throwable}., Serialized Form

Method Summary

Modifier and Type	Method and Description
static TruffleStackTrace	fillIn(Throwable throwable) Fills in the guest language stack frames from the current frames on the stack.
Throwable	fillInStackTrace()
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.
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.
String	toString()

Methods inherited from class java.lang.Throwable

addSuppressed, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

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 TruffleStackTrace.fillIn(Throwable), so it is not necessary to call TruffleStackTrace.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