+=back
+
+
+=head2 Using G_KEEPERR
+
+Consider this rather facetious example, where we have used an XS
+version of the call_Subtract example above inside a destructor:
+
+ package Foo;
+ sub new { bless {}, $_[0] }
+ sub Subtract {
+ my($a,$b) = @_;
+ die "death can be fatal" if $a < $b;
+ $a - $b;
+ }
+ sub DESTROY { call_Subtract(5, 4); }
+ sub foo { die "foo dies"; }
+
+ package main;
+ {
+ my $foo = Foo->new;
+ eval { $foo->foo };
+ }
+ print "Saw: $@" if $@; # should be, but isn't
+
+This example will fail to recognize that an error occurred inside the
+C<eval {}>. Here's why: the call_Subtract code got executed while perl
+was cleaning up temporaries when exiting the outer braced block, and because
+call_Subtract is implemented with I<call_pv> using the G_EVAL
+flag, it promptly reset C<$@>. This results in the failure of the
+outermost test for C<$@>, and thereby the failure of the error trap.
+
+Appending the G_KEEPERR flag, so that the I<call_pv> call in
+call_Subtract reads:
+
+ count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
+
+will preserve the error and restore reliable error handling.
+
+=head2 Using call_sv
+
+In all the previous examples I have 'hard-wired' the name of the Perl
+subroutine to be called from C. Most of the time though, it is more
+convenient to be able to specify the name of the Perl subroutine from
+within the Perl script.
+
+Consider the Perl code below
+
+ sub fred
+ {
+ print "Hello there\n";
+ }
+
+ CallSubPV("fred");
+
+Here is a snippet of XSUB which defines I<CallSubPV>.
+
+ void
+ CallSubPV(name)
+ char * name
+ CODE:
+ PUSHMARK(SP);
+ call_pv(name, G_DISCARD|G_NOARGS);
+
+That is fine as far as it goes. The thing is, the Perl subroutine
+can be specified as only a string, however, Perl allows references
+to subroutines and anonymous subroutines.
+This is where I<call_sv> is useful.
+
+The code below for I<CallSubSV> is identical to I<CallSubPV> except
+that the C<name> parameter is now defined as an SV* and we use
+I<call_sv> instead of I<call_pv>.
+
+ void
+ CallSubSV(name)
+ SV * name
+ CODE:
+ PUSHMARK(SP);
+ call_sv(name, G_DISCARD|G_NOARGS);
+
+Because we are using an SV to call I<fred> the following can all be used:
+
+ CallSubSV("fred");
+ CallSubSV(\&fred);
+ $ref = \&fred;
+ CallSubSV($ref);
+ CallSubSV( sub { print "Hello there\n" } );
+
+As you can see, I<call_sv> gives you much greater flexibility in
+how you can specify the Perl subroutine.
+
+You should note that, if it is necessary to store the SV (C<name> in the
+example above) which corresponds to the Perl subroutine so that it can
+be used later in the program, it not enough just to store a copy of the
+pointer to the SV. Say the code above had been like this:
+
+ static SV * rememberSub;
+
+ void
+ SaveSub1(name)
+ SV * name
+ CODE:
+ rememberSub = name;
+
+ void
+ CallSavedSub1()
+ CODE:
+ PUSHMARK(SP);
+ call_sv(rememberSub, G_DISCARD|G_NOARGS);
+
+The reason this is wrong is that, by the time you come to use the
+pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
+to the Perl subroutine that was recorded in C<SaveSub1>. This is
+particularly true for these cases:
+
+ SaveSub1(\&fred);
+ CallSavedSub1();
+
+ SaveSub1( sub { print "Hello there\n" } );
+ CallSavedSub1();
+
+By the time each of the C<SaveSub1> statements above has been executed,
+the SV*s which corresponded to the parameters will no longer exist.
+Expect an error message from Perl of the form
+
+ Can't use an undefined value as a subroutine reference at ...
+
+for each of the C<CallSavedSub1> lines.
+
+Similarly, with this code
+
+ $ref = \&fred;
+ SaveSub1($ref);
+ $ref = 47;
+ CallSavedSub1();
+
+you can expect one of these messages (which you actually get is dependent on
+the version of Perl you are using)
+
+ Not a CODE reference at ...
+ Undefined subroutine &main::47 called ...
+
+The variable $ref may have referred to the subroutine C<fred>
+whenever the call to C<SaveSub1> was made but by the time
+C<CallSavedSub1> gets called it now holds the number C<47>. Because we
+saved only a pointer to the original SV in C<SaveSub1>, any changes to
+$ref will be tracked by the pointer C<rememberSub>. This means that
+whenever C<CallSavedSub1> gets called, it will attempt to execute the
+code which is referenced by the SV* C<rememberSub>. In this case
+though, it now refers to the integer C<47>, so expect Perl to complain
+loudly.
+
+A similar but more subtle problem is illustrated with this code:
+
+ $ref = \&fred;
+ SaveSub1($ref);
+ $ref = \&joe;
+ CallSavedSub1();
+
+This time whenever C<CallSavedSub1> gets called it will execute the Perl
+subroutine C<joe> (assuming it exists) rather than C<fred> as was
+originally requested in the call to C<SaveSub1>.
+
+To get around these problems it is necessary to take a full copy of the
+SV. The code below shows C<SaveSub2> modified to do that.
+
+ static SV * keepSub = (SV*)NULL;
+
+ void
+ SaveSub2(name)
+ SV * name
+ CODE:
+ /* Take a copy of the callback */
+ if (keepSub == (SV*)NULL)
+ /* First time, so create a new SV */
+ keepSub = newSVsv(name);
+ else
+ /* Been here before, so overwrite */
+ SvSetSV(keepSub, name);
+
+ void
+ CallSavedSub2()
+ CODE:
+ PUSHMARK(SP);
+ call_sv(keepSub, G_DISCARD|G_NOARGS);
+
+To avoid creating a new SV every time C<SaveSub2> is called,
+the function first checks to see if it has been called before. If not,
+then space for a new SV is allocated and the reference to the Perl
+subroutine C<name> is copied to the variable C<keepSub> in one
+operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called,
+the existing SV, C<keepSub>, is overwritten with the new value using
+C<SvSetSV>.
+
+=head2 Using call_argv
+
+Here is a Perl subroutine which prints whatever parameters are passed
+to it.
+
+ sub PrintList
+ {
+ my(@list) = @_;
+
+ foreach (@list) { print "$_\n" }
+ }
+
+And here is an example of I<call_argv> which will call
+I<PrintList>.
+
+ static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
+
+ static void
+ call_PrintList()
+ {
+ dSP;
+
+ call_argv("PrintList", G_DISCARD, words);
+ }
+
+Note that it is not necessary to call C<PUSHMARK> in this instance.
+This is because I<call_argv> will do it for you.
+
+=head2 Using call_method
+
+Consider the following Perl code:
+
+ {
+ package Mine;
+
+ sub new
+ {
+ my($type) = shift;
+ bless [@_]
+ }
+
+ sub Display
+ {
+ my ($self, $index) = @_;
+ print "$index: $$self[$index]\n";
+ }
+
+ sub PrintID
+ {
+ my($class) = @_;
+ print "This is Class $class version 1.0\n";
+ }
+ }
+
+It implements just a very simple class to manage an array. Apart from
+the constructor, C<new>, it declares methods, one static and one
+virtual. The static method, C<PrintID>, prints out simply the class
+name and a version number. The virtual method, C<Display>, prints out a
+single element of the array. Here is an all-Perl example of using it.
+
+ $a = Mine->new('red', 'green', 'blue');
+ $a->Display(1);
+ Mine->PrintID;
+
+will print
+
+ 1: green
+ This is Class Mine version 1.0
+
+Calling a Perl method from C is fairly straightforward. The following
+things are required: