com.oracle.truffle.api.exception

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:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	UNLIMITED_STACK_TRACE The constant for an unlimited stack trace element limit.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractTruffleException() Creates a new AbstractTruffleException.
protected	AbstractTruffleException(AbstractTruffleException prototype) Creates a new AbstractTruffleException initialized from the given prototype.
protected	AbstractTruffleException(Node location) Creates a new AbstractTruffleException with given location.
protected	AbstractTruffleException(String message) Creates a new AbstractTruffleException with given message.
protected	AbstractTruffleException(String message, Node location) Creates a new AbstractTruffleException with given message and location.
protected	AbstractTruffleException(String message, Throwable cause, int stackTraceElementLimit, Node location) Creates a new AbstractTruffleException.

Method Summary

Modifier and Type	Method and Description
Throwable	fillInStackTrace()
Throwable	getCause()
Node	getLocation() Returns a node indicating the location where this exception occurred in the AST.
int	getStackTraceElementLimit() Returns the number of guest language frames that should be collected for this exception.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

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

Field Detail

UNLIMITED_STACK_TRACE

public static final int UNLIMITED_STACK_TRACE

The constant for an unlimited stack trace element limit.

Since:

20.3

See Also:

Constant Field Values

Constructor Detail

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 AbstractTruffleException.UNLIMITED_STACK_TRACE for unlimited stack trace length.

Since:

20.3

Method Detail

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

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