Qore Programming Language Reference Manual: Exception Handling

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

All Classes Namespaces Functions Variables Groups Pages
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 function 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.

The exception hash contains the following members:

Exception Hash Keys

Name | Type | Description
`type` | string | see Exception Type Constants for possible values
`file` | string | The parse label where exception occurred; this is normally the file name; this corresponds to the label parameter of the Program::parse() and Program::parsePending() methods and the Qore::parse() function, for example
`line` | int | The starting line number where exception occurred
`endline` | int | The ending line number where the exception occurred
`source` | *string | An optional source string for the exception; if multiple sections of a file were parsed with different parse labels, then the source file name will normally go here and the `"file"` key will have the parse label; this corresponds to the source parameter of the Program::parse() and Program::parsePending() methods, for example
`offset` | int | The line number offset for the `"source"` key
`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.

Call Stack Description

Name | Type | Description
`function` | string | function name of the source where the exception was raised (if known)
`file` | string | The parse label where exception occurred; this is normally the file name; this corresponds to the label parameter of the Program::parse() and Program::parsePending() methods and the Qore::parse() function, for example (if known, for user exceptions only)
`line` | int | The starting line number where exception occurred (if known, for user exceptions only)
`endline` | int | The ending line number where the exception occurred (if known, for user exceptions only)
`source` | *string | An optional source string for the exception; if multiple sections of a file were parsed with different parse labels, then the source file name will normally go here and the `"file"` key will have the parse label; this corresponds to the source parameter of the Program::parse() and Program::parsePending() methods, for example (if known, for user exceptions only)
`offset` | int | The line number offset for the `"source"` key (if known, for user exceptions only)
`type` | string | `"user"`, `"builtin"`, or `"rethrow"`
`typecode` | int | see Call Type Constants for possible values

System exceptions always throw at least 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, 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.