Class AbstractTruffleException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
com.oracle.truffle.api.exception.AbstractTruffleException
All Implemented Interfaces:
TruffleObject, Serializable
public abstract class AbstractTruffleException extends RuntimeException implements TruffleObject
A base class for an exception thrown during the execution of a guest language program.
The following snippet shows the guest language exception implementation. 
final class MyLanguageException extends AbstractTruffleException {
    MyLanguageException(String message, Node location) {
        super(message, location);
    }
}
The following snippet shows a typical implementation of a syntax error exception supporting also incomplete sources. 
@ExportLibrary(InteropLibrary.class)
final class MyLanguageParseError extends AbstractTruffleException {
    private final Source source;
    private final int line;
    private final int column;
    private final int length;
    private final boolean incompleteSource;

    MyLanguageParseError(Source source, int line, int column, int length, boolean incomplete, String message) {
        super(message);
        this.source = source;
        this.line = line;
        this.column = column;
        this.length = length;
        this.incompleteSource = incomplete;
    }

    @ExportMessage
    ExceptionType getExceptionType() {
        return ExceptionType.PARSE_ERROR;
    }

    @ExportMessage
    boolean isExceptionIncompleteSource() {
        return incompleteSource;
    }

    @ExportMessage
    boolean hasSourceLocation() {
        return source != null;
    }

    @ExportMessage(name = "getSourceLocation")
    SourceSection getSourceSection() throws UnsupportedMessageException {
        if (source == null) {
            throw UnsupportedMessageException.create();
        }
        return source.createSection(line, column, length);
    }
}
The following snippet shows a typical implementation of an interrupt exception. 
@ExportLibrary(InteropLibrary.class)
final class MyLanguageInterruptException extends AbstractTruffleException {

    MyLanguageInterruptException(String message, Node location) {
        super(message, location);
    }

    @ExportMessage
    ExceptionType getExceptionType() {
        return ExceptionType.INTERRUPT;
    }
}
The following snippet shows a typical implementation of an soft exit exception. 
@ExportLibrary(InteropLibrary.class)
final class MyLanguageExitException extends AbstractTruffleException {

    private final int exitStatus;

    MyLanguageExitException(String message, int exitStatus, Node location) {
        super(message, location);
        this.exitStatus = exitStatus;
    }

    @ExportMessage
    ExceptionType getExceptionType() {
        return ExceptionType.EXIT;
    }

    @ExportMessage
    int getExceptionExitStatus() {
        return exitStatus;
    }
}
Since:
20.3
See Also:

  • Field Details

    • UNLIMITED_STACK_TRACE

      public static final int UNLIMITED_STACK_TRACE
      The constant for an unlimited stack trace element limit.
      Since:
      20.3
      See Also:

  • Constructor Details

    • AbstractTruffleException

      protected AbstractTruffleException()
      Creates a new AbstractTruffleException.
      Since:
      20.3

    • AbstractTruffleException

      protected AbstractTruffleException(Node location)
      Creates a new AbstractTruffleException with given location.
      Since:
      20.3

    • AbstractTruffleException

      protected AbstractTruffleException(String message)
      Creates a new AbstractTruffleException with given message.
      Since:
      20.3

    • AbstractTruffleException

      protected AbstractTruffleException(String message, Node location)
      Creates a new AbstractTruffleException with given message and location.
      Since:
      20.3

    • AbstractTruffleException

      protected AbstractTruffleException(AbstractTruffleException prototype)
      Creates a new AbstractTruffleException initialized from the given prototype. The exception message, internal cause, stack trace limit, location, suppressed exceptions and Truffle stack trace of a newly created AbstractTruffleException are inherited from the given AbstractTruffleException.
      Since:
      20.3

    • AbstractTruffleException

      protected AbstractTruffleException(String message, Throwable cause, int stackTraceElementLimit, Node location)
      Creates a new AbstractTruffleException.
      Parameters:
      message - the exception message or null
      cause - an internal or AbstractTruffleException causing this exception or null. If internal errors are passed as cause, they are not accessible by other languages or the embedder. In other words, InteropLibrary.getExceptionCause(Object) or Throwable.getCause() will return null for internal errors.
      stackTraceElementLimit - a stack trace limit. Use UNLIMITED_STACK_TRACE for unlimited stack trace length.
      Since:
      20.3

  • Method Details

    • fillInStackTrace

      public final Throwable fillInStackTrace()
      Overrides:
      fillInStackTrace in class Throwable
      Since:
      20.3

    • getLocation

      public final Node getLocation()
      Returns a node indicating the location where this exception occurred in the AST. This method may return null to indicate that the location is not available.
      Since:
      20.3

    • getEncapsulatingSourceSection

      public SourceSection getEncapsulatingSourceSection()
      Returns a source section associated with the exception. This method may return null to indicate that the source section is not available.

      Note: This method is expensive as it requires to access the current stack trace to get the to-most source section.

      Since:
      24.2

    • getStackTraceElementLimit

      public final int getStackTraceElementLimit()
      Returns the number of guest language frames that should be collected for this exception. Returns a negative integer by default for unlimited guest language frames. This is intended to be used by guest languages to limit the number of guest language stack frames. Languages might want to limit the number of frames for performance reasons. Only frames whose RootNode.countsTowardsStackTraceLimit() method return true count towards the limit.
      Since:
      20.3

    • getCause

      public final Throwable getCause()
      Overrides:
      getCause in class Throwable
      Since:
      20.3