Home | | LPC | Copyright © 2009. Available under the terms of the GPL.

MudOS LPC Module - exception


The exception module provides structured exception handling for LPC. This module coordinates with the master and sefun objects to provide stack traces for structured and unstructured exceptions. A structured exception has type, optional informational arguments, and an optional cause. Structured exceptions are thrown by the functions in this module. An unstructured exception has an error message only. Unstructured exceptions are thrown by the driver, the error efun, or the throw efun.
Files:
/include/module/exception.h
/master/exception.c
/module/exception.c
/sefun/exception.c

Function Summary
#define
[mixed]
exception_catch(EXPR)
          Executes an expression while catching exceptions.
#define
[mixed]
exception_catch_block(BLOCK)
          Executes a block while catching exceptions.
string exception_format(mixed exception, int [bool] stack)
          Formats an exception for display.
mixed exception_get_argument(mixed exception, int index)
          Returns an informational argument of the structured exception.
string exception_get_error(mixed exception)
          Returns the error message of the unstructured exception.
int exception_get_sizeof_arguments(mixed exception)
          Returns the number of informational arguments of the structured exception.
string exception_get_type(mixed exception)
          Returns the type of the exception, or false if the exception was unstructured.
void exception_rethrow(mixed exception)
          Rethrows an exception that was previously caught.
void exception_throw(string type, mixed [string|int] *arguments...)
          Throws a structured exception.
void exception_throw_caused(mixed cause, string type, mixed [string|int] *arguments...)
          Throws a structured exception that was caused by another exception.

Function Detail

exception_catch

#define [mixed] exception_catch(EXPR)
Executes an expression while catching exceptions. Example:
mixed exc;
if ((exc = exception_catch(...)))
    ...

Parameters:
EXPR - an LPC expression
Returns:
an exception value, or false if no error occurred

exception_catch_block

#define [mixed] exception_catch_block(BLOCK)
Executes a block while catching exceptions. Example:
mixed exc;
if ((exc = exception_catch_block({ ... })))
    ...

Parameters:
BLOCK - an LPC block
Returns:
an exception value, or false if no error occurred

exception_throw

void exception_throw(string type,
                     mixed [string|int] *arguments...)
Throws a structured exception. By convention, exception types are identifiers delimited by "/". Unless the type is sufficient to explain the reason for the exception, the first exception information argument usually contains a message explaining the reason the exception was thrown.

Parameters:
type - the exception message
arguments - additional exception information

exception_throw_caused

void exception_throw_caused(mixed cause,
                            string type,
                            mixed [string|int] *arguments...)
Throws a structured exception that was caused by another exception.

Parameters:
cause - the exception cause
type - the exception message
arguments - additional exception information

exception_rethrow

void exception_rethrow(mixed exception)
Rethrows an exception that was previously caught.

Parameters:
exception - the exception

exception_get_type

string exception_get_type(mixed exception)
Returns the type of the exception, or false if the exception was unstructured.

Parameters:
exception - the exception
Returns:
the exception type

exception_get_error

string exception_get_error(mixed exception)
Returns the error message of the unstructured exception. This function must only be called for unstructured exceptions.

Parameters:
exception - the unstructured exception
Returns:
the error message

exception_get_sizeof_arguments

int exception_get_sizeof_arguments(mixed exception)
Returns the number of informational arguments of the structured exception. This function must only be called for structured exceptions.

Parameters:
exception - the structured exception
Returns:
the number of informational arguments

exception_get_argument

mixed exception_get_argument(mixed exception,
                             int index)
Returns an informational argument of the structured exception. This function must only be called for structured exceptions. The index must be non-negative and less than exception_get_sizeof_arguments.

Parameters:
exception - the structured exception
index - the argument index
Returns:
an informational argument

exception_format

string exception_format(mixed exception,
                        int [bool] stack)
Formats an exception for display. The following shows example output from this function when the stack argument is true:
example/type: message
	at /example/exception::throw_func(/example/exception.c:7)
	at /example/exception::<catch>(/example/exception.c:14)
	at /example/exception::create(/example/exception.c:14)

If the exception is thrown using exception_throw_caused, then the following shows example output from this function:

example/type: message
	at /example/exception2::throw_caused_func(/example/exception2:12)
	at /example/exception2::<catch>(/example/exception2:19)
	at /example/exception2::create(/example/exception2:19)
Caused by: example/cause: message
	at /example/exception2::throw_func(/example/exception2:7)
	at /example/exception2::<catch>(/example/exception2:12)
	... 3 more

Parameters:
exception - the exception
stack - true if the stack trace and causal exceptions should be included
Returns:
a newline-terminated string