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

FreeBSD Manual Pages

  
 
  

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

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

NAME | DESCRIPTION | Exception handlers | METHODS | ACCESSORS | CLASS METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ExtUtils::XSpp::Exception&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help