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 |
---|---|---|
| string | "System" or "User" depending on exception type |
| string | File name of file where exception occurred |
| integer | Line number where exception occurred |
| list of hashes | Backtrace information |
| 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. |
| 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. |
| 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 |
---|---|---|
| string | function name |
| integer | line number |
| string | file name |
| string | Exception Type (ET_*) constants; see Exception Constants for values. |
| 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.