Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ExtUtils::XSpp::ExceptUser3Contributed Perl DocumeExtUtils::XSpp::Exception(3)

       ExtUtils::XSpp::Exception - Map C++ exceptions to Perl exceptions

       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!";
	 //   }
	 // }


       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)

       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":

	 implements the	most general case of simply throwing a generic error
	 message that includes the name	of the C++ exception type.

	 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.

	 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().

	 maps C++ exceptions to	throwing an instance of	some Perl exception



	 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.

	 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

       There is	a special exception handler "nothing" which is always

	 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.

       Creates a new "ExtUtils::XSpp::Exception".

       Calls the "$self->init(@_)" method after	construction.  "init()"	must
       be overridden in	subclasses.

       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.

       Given a piece of	code and a number of spaces to use for global
       indentation, indents the	code and returns it.

       Fetches the C++ type of the exception from the "type" attribute and
       returns it.

       Returns the name	of the exception.  This	is the "myException" in

       Returns the ExtUtils::XSpp::Node::Type C++ type that is used for	this
       exception.  This	is the "char*" in

       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.

       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.32.1			  2021-02-28	  ExtUtils::XSpp::Exception(3)


Want to link to this manual page? Use this URL:

home | help