Add in perldelta changes about unpack A and trailing whitespace, trie

[p5sagit/p5-mst-13.2.git] / pod / perlguts.pod

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 5eb46d2..d95d3e4 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -2260,6 +2260,39 @@ and
         AV *av = ...;
         UV  uv = PTR2UV(av);
 
+=head2 Exception Handling
+
+There are a couple of macros to do very basic exception handling in XS
+modules. You have to define C<NO_XSLOCKS> before including F<XSUB.h> to
+be able to use these macros:
+
+        #define NO_XSLOCKS
+        #include "XSUB.h"
+
+You can use these macros if you call code that may croak, but you need
+to do some cleanup before giving control back to Perl. For example:
+
+        dXCPT;    /* set up neccessary variables */
+
+        XCPT_TRY_START {
+          code_that_may_croak();
+        } XCPT_TRY_END
+
+        XCPT_CATCH
+        {
+          /* do cleanup here */
+          XCPT_RETHROW;
+        }
+
+Note that you always have to rethrow an exception that has been
+caught. Using these macros, it is not possible to just catch the
+exception and ignore it. If you have to ignore the exception, you
+have to use the C<call_*> function.
+
+The advantage of using the above macros is that you don't have
+to setup an extra function for C<call_*>, and that using these
+macros is faster than using C<call_*>.
+
 =head2 Source Documentation
 
 There's an effort going on to document the internal functions and
@@ -2283,6 +2316,26 @@ source, like this:
 Please try and supply some documentation if you add functions to the
 Perl core.
 
+=head2 Backwards compatibility
+
+The Perl API changes over time. New functions are added or the interfaces
+of existing functions are changed. The C<Devel::PPPort> module tries to
+provide compatibility code for some of these changes, so XS writers don't
+have to code it themselves when supporting multiple versions of Perl.
+
+C<Devel::PPPort> generates a C header file F<ppport.h> that can also
+be run as a Perl script. To generate F<ppport.h>, run:
+
+    perl -MDevel::PPPort -eDevel::PPPort::WriteFile
+
+Besides checking existing XS code, the script can also be used to retrieve
+compatibility information for various API calls using the C<--api-info>
+command line switch. For example:
+
+  % perl ppport.h --api-info=sv_magicext
+
+For details, see C<perldoc ppport.h>.
+
 =head1 Unicode Support
 
 Perl 5.6.0 introduced Unicode support. It's important for porters and XS