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.