Exception:
Filter:
Classes | Core

Exception : Object

root error class
Source: Error.sc
Subclasses: Error
 

Description

The root of SuperCollider's error handling mechanism.

Exception is an abstract class, defining basic error behavior. This class is not directly used in SuperCollider. Users may create subclasses of Exception to identify specific types of failure conditions.

The built-in exception types are actually subclasses of Error -- see its help file for the hierarchy.

NOTE: You should not return ^ from inside of the try or protect function itself, it cannot be caught. Returns in methods called by the receiver are OK.

Background: General exception handling

An exception is any event that disrupts the normal execution flow of a program. In practice there is not much distinction between an exception and an error; in SuperCollider, we tend to speak of errors where other object-oriented languages (Java, C++) would use exception consistently.

If a piece of code runs into an unexpected condition, it creates an exception object that holds information about the faulty condition, and then "throws" that object. From there, the interpreter unwinds backward through all the preceding stack frames looking for an exception handler that will "catch" the exception. The exception handler can take an alternate route to resolve the failure and continue normally; if this is not possible, it can re-throw the exception back to the previous stack frame. An exception that never gets caught causes execution to abort. In SuperCollider, this results in the standard error dump (see the Understanding-Errors help file for details); in C++ or Java, the effect is catastrophic, causing the whole program to crash.

Common syntax in other languages for exception handling is:

Specific languages may have other variants. The SuperCollider compiler doesn't have room for the "catch" keyword, so the syntax is simpler:

With "try", "if" the error cannot be handled, you have to re-throw the error explicitly:

SuperCollider includes a variant, borrowed from Scheme, in which the exception is always fatal, but the preceding code might have allocated some resources that need to be released before reporting the error. For example, you might open a file and do some processing on it that might encounter an error. Good practice is to close the file before the error halt, which you can do this way:

With "protect" the second function will execute even if there is no error, and any error will be passed up the chain.

In Java, you can catch specific classes of exception. You can simulate this usage with the following construction:

Following is an example that recovers from a failed attempt to write into an immutable array, by re-attempting the write on a copy of the array.

Class Methods

Inherited class methods

Undocumented class methods

Exception.debug

Exception.debug = value

Exception.handling

Exception.handling = value

Exception.inProtectedFunction

Exception.inProtectedFunction = value

Exception.new(what)

Instance Methods

Inherited instance methods

Undocumented instance methods

.adviceLink

.adviceLinkPage

.errorString

.isException

.path

.path = value

.postProtectedBacktrace

.protectedBacktrace

.protectedBacktrace = value

.reportError

.what

.what = value