2.21. Exception Handling

Exceptions are errors that can only be handled using a try catch block. Any exception that is thrown in a try block will immediately cause execution of that thread to begin with the first statement of the catch block, regardless of the position of the program pointer of the running thread, even if nested subroutines or object method calls have been made.

Exceptions can be thrown by the Qore system for a number of reasons, see the documentation for each function and object method for details.

Programmers can also throw exceptions explicitly by using the throw and rethrow statements.

Information about the exception, including the context in which the exception occurred, is saved in the exception hash, which can be retrieved by using a parameter variable in the catch block (for more information about try catch blocks, see try and catch statements).

The exception hash contains the following members:

Table 2.91. Exception Hash Keys

Name

Type

Description

type

string

"System" or "User" depending on exception type

file

string

File name of file where exception occurred

line

integer

Line number where exception occurred

callStack

list of hashes

Backtrace information

err

any

This key is populated with the value of the first expression of the throw statement. For system exceptions, this is a string giving the exception code.

desc

any

This key is populated with the value of the second expression of the throw statement (if a list was thrown). For system exceptions, this is a string giving a text description of the error.

arg

any

This key is populated with the value of the third expression of the throw statement (if a list was thrown). For system exceptions, this is populated for some exceptions where additional information is provided.


Table 2.92. Call Stack Description

Name

Type

Description

function

string

function name

line

integer

line number

file

string

file name

type

string

Exception Type (ET_*) constants; see Exception Constants for values.

typecode

integer

Call Type (CT_*) constants; see Exception Constants for values.


System exceptions always throw 2 values, populating the "err" and "desc" keys of the exception hash, giving the exception string code and the exception description string, respectively, and occassionally, depending on the function, the "arg" key may be populated with supporting information. User exceptions have no restrictions, any values given in the throw statement will be mapped to exception keys as per the table above.

See the on_exit statement, on_success statement, and on_error statement for statements that allow for exception-safe and exception-dependent cleanup in Qore code.

Classes that assist in exception-safe lock handling are the AutoLock class, the AutoGate class, the AutoReadLock class, and the AutoWriteLock class.