ExtUtils::XSpp::ExceptUser3Contributed Perl DocumeExtUtils::XSpp::Exception(3)NAMEExtUtils::XSpp::Exception - Map C++ exceptions to Perl exceptions
DESCRIPTION
This class is both the base class for the different exception handling
mechanisms and the container for the global set of exception mappings
from C++ exceptions (indicated by a C++ data type to catch) to Perl
exceptions. The Perl exceptions are implemented via "croak()".
The basic idea is that you can declare the C++ exception types that you
want to handle and how you plan to do so by using the %exception
directive in your XS++ (or better yet, in the XS++ typemap):
// OutOfBoundsException would have been declared
// elsewhere as:
//
// class OutOfBoundsException : public std::exception {
// public:
// OutOfBoundsException() {}
// virtual const char* what() const throw() {
// return "You accessed me out of bounds, fool!";
// }
// }
%exception{outOfBounds}{OutOfBoundsException}{stdmessage};
If you know a function or method may throw "MyOutOfBoundsException"s,
you can annotate the declaration in your XS++ as follows:
double get_from_array(unsigned int index)
%catch{outOfBounds};
When "get_from_array" now throws an "OutOfBoundsException", the user
gets a Perl croak with the message "Caught exception of type
'OutOfBoundsException': You accessed me out of bounds, fool!". There
may be any number of %catch directives per method.
Note: Why do we assign another name ("outOfBounds") to the existing
"OutOfBoundsException"? Because you may need to catch exceptions of
the same C++ type with different handlers for different methods. You
can, in principle, re-use the C++ exception class name for the
exception map name, but that may be confusing to posterity.
Instead of adding %catch to methods, you may also specify exceptions
that you wish to handle for all methods of a class:
class Foo %catch{SomeException,AnotherException} {
...
};
The %catch{Foo,Bar,...} syntax is shorthand for "%catch{Foo}
%catch{Bar} ...". If there are exceptions to be caught both from the
class and attached to a method directly, the exceptions that are
attached to the method only will be handled first. No single type of
exceptions will be handled more than once, therefore it is safe to use
this precedence to re-order the class-global exception handling for a
single method.
If there are no %catch decorators on a method, exceptions derived from
"std::exception" will be caught with a generic "stdmessage" handler
such as above. Even if there are %catch clauses for the given method,
all otherwise uncaught exceptions will be caught with a generic error
message for safety.
Exception handlers
There are different cases of Perl exceptions that are implemented as
sub-classes of "ExtUtils::XSpp::Exception":
ExtUtils::XSpp::Exception::simple
implements the most general case of simply throwing a generic error
message that includes the name of the C++ exception type.
ExtUtils::XSpp::Exception::stdmessage
handles C++ exceptions that are derived from "std::exception" and
which provide a "char* what()" method that will provide an error
message. The Perl-level error message will include the C++ exception
type name and the exception's "what()" message.
ExtUtils::XSpp::Exception::code
allows the user to supply custom C/C++/XS code that will be included
in the exception handler verbatim. The code has access to the
exception object as the variable "e". Your user supplied code is
expected to propagate the exception to Perl by calling croak().
ExtUtils::XSpp::Exception::object
maps C++ exceptions to throwing an instance of some Perl exception
class.
Syntax:
%exception{myClassyException}{CppException}{object}{PerlClass};
Currently, this means just calling "PerlClass->new()" and then
die()ing with that object in $@. There is no good way to pass
information from the C++ exception object to the Perl object. Will
change in future.
ExtUtils::XSpp::Exception::unknown
is the default exception handler that is added to the list of
handlers automatically during code generation. It simply throws an
entirely unspecific error and catches the type "..." (meaning
anything).
There is a special exception handler "nothing" which is always
available:
int foo() %catch{nothing};
It indicates that the given method (or function) is to handle no
exceptions. It squishes any exception handlers that might otherwise be
inherited from the method's class.
METHODS
new
Creates a new "ExtUtils::XSpp::Exception".
Calls the "$self->init(@_)" method after construction. "init()" must
be overridden in subclasses.
handler_code
Unimplemented in this base class, but must be implemented in all actual
exception classes.
Generates the "catch(){}" block of code for inclusion in the XS output.
First (optional) argument is an integer indicating the number of spaces
to use for the first indentation level.
indent_code
Given a piece of code and a number of spaces to use for global
indentation, indents the code and returns it.
cpp_type
Fetches the C++ type of the exception from the "type" attribute and
returns it.
ACCESSORS
name
Returns the name of the exception. This is the "myException" in
%exception{myException}{char*}{handler}.
type
Returns the ExtUtils::XSpp::Node::Type C++ type that is used for this
exception. This is the "char*" in
%exception{myException}{char*}{handler}.
CLASS METHODS
add_exception
Given an "ExtUtils::XSpp::Exception" object, adds this object to the
global registry, potentially overwriting an exception map of the same
name that was in effect before.
get_exception_for_name
Given the XS++ name of the exception map, fetches the corresponding
"ExtUtils::XSpp::Exception" object from the global registry and returns
it. Croaks on error.
perl v5.14.1 2011-07-25 ExtUtils::XSpp::Exception(3)
