perl5.001 patch.1f

This patch only includes updates for perlapi.pod, perlbot.pod,
perlcall.pod, and perlguts.pod from the authors.

1 files changed, 1373 insertions, 375 deletions

diff --git a/pod/perlcall.pod b/pod/perlcall.pod
index d81ee4a9ec..bde86796ac 100644
--- a/pod/perlcall.pod
+++ b/pod/perlcall.pod
@@ -4,255 +4,454 @@ perlcall - Perl calling conventions from C
 
 =head1 DESCRIPTION
 
-B<WARNING : This document is still under construction. 
-There are bound to be a number of inaccuracies, so tread very carefully for now.>
+The purpose of this document is to show you how to call Perl subroutines
+directly from C, i.e. how to write I<callbacks>.
 
-The purpose of this document is to show you how to write I<callbacks>, 
-i.e. how to call Perl from C. The main
-focus is on how to interface back to Perl from a bit of C code that has itself
-been run by Perl, i.e. the 'main' program is a Perl script; you are using it
-to execute
-a section of code written in C; that bit of C code wants you to do something
-with a particular event, so you want a Perl sub to be executed whenever it
-happens.
+Apart from discussing the C interface provided by Perl for writing
+callbacks the document uses a series of examples to show how the
+interface actually works in practice.  In addition some techniques for
+coding callbacks are covered.
 
-Examples where this is necessary include
+Examples where callbacks are necessary include
 
 =over 5
 
-=item * 
+=item * An Error Handler
 
 You have created an XSUB interface to an application's C API.
 
 A fairly common feature in applications is to allow you to define a C
-function that will get called whenever something nasty occurs.
-What we would like is for a Perl sub to be called instead.
+function that will be called whenever something nasty occurs. What we
+would like is to be able to specify a Perl subroutine that will be
+called instead.
 
-=item *
+=item * An Event Driven Program
 
-The classic example of where callbacks are used is in an event driven program 
-like for X-windows.
-In this case your register functions to be called whenever a specific events
-occur, e.g. a mouse button is pressed.
+The classic example of where callbacks are used is when writing an
+event driven program like for an X windows application.  In this case
+your register functions to be called whenever specific events occur,
+e.g. a mouse button is pressed, the cursor moves into a window or a
+menu item is selected.
 
 =back
 
-Although the techniques described are applicable to embedding Perl
-in a C program, this is not the primary goal of this document. For details
-on embedding Perl in C refer to L<perlembed> (currently unwritten).
+Although the techniques described here are applicable when embedding
+Perl in a C program, this is not the primary goal of this document.
+There are other details that must be considered and are specific to
+embedding Perl. For details on embedding Perl in C refer to
+L<perlembed>.
 
-Before you launch yourself head first into the rest of this document, it would 
-be a good idea to have read the following two documents - L<perlapi> and L<perlguts>.
+Before you launch yourself head first into the rest of this document,
+it would be a good idea to have read the following two documents -
+L<perlapi> and L<perlguts>.
 
-This stuff is easier to explain using examples. But first here are a few
-definitions anyway.
+=head1 THE PERL_CALL FUNCTIONS
 
-=head2 Definitions
+Although this stuff is easier to explain using examples, you first need
+be aware of a few important definitions.
 
-Perl has a number of C functions which allow you to call Perl subs. They are
+Perl has a number of C functions that allow you to call Perl
+subroutines.  They are
 
     I32 perl_call_sv(SV* sv, I32 flags) ;
     I32 perl_call_pv(char *subname, I32 flags) ;
     I32 perl_call_method(char *methname, I32 flags) ;
     I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;
 
-The key function is I<perl_call_sv>. All the other functions make use of
-I<perl_call_sv> to do what they do.
+The key function is I<perl_call_sv>.  All the other functions are
+fairly simple wrappers which make it easier to call Perl subroutines in
+special cases. At the end of the day they will all call I<perl_call_sv>
+to actually invoke the Perl subroutine.
+
+All the I<perl_call_*> functions have a C<flags> parameter which is
+used to pass a bit mask of options to Perl.  This bit mask operates
+identically for each of the functions.  The settings available in the
+bit mask are discussed in L<FLAG VALUES>.
+
+Each of the functions will now be discussed in turn.
+
+=over 5
+
+=item B<perl_call_sv>
+
+I<perl_call_sv> takes two parameters, the first, C<sv>, is an SV*.
+This allows you to specify the Perl subroutine to be called either as a
+C string (which has first been converted to an SV) or a reference to a
+subroutine. The section, I<Using perl_call_sv>, shows how you can make
+use of I<perl_call_sv>.
+
+=item B<perl_call_pv>
+
+The function, I<perl_call_pv>, is similar to I<perl_call_sv> except it
+expects its first parameter to be a C char* which identifies the Perl
+subroutine you want to call, e.g. C<perl_call_pv("fred", 0)>.  If the
+subroutine you want to call is in another package, just include the
+package name in the string, e.g. C<"pkg::fred">.
+
+=item B<perl_call_method>
+
+The function I<perl_call_method> is used to call a method from a Perl
+class.  The parameter C<methname> corresponds to the name of the method
+to be called.  Note that the class that the method belongs to is passed
+on the Perl stack rather than in the parameter list. This class can be
+either the name of the class (for a static method) or a reference to an
+object (for a virtual method).  See L<perlobj> for more information on
+static and virtual methods and L<Using perl_call_method> for an example
+of using I<perl_call_method>.
+
+=item B<perl_call_argv>
+
+I<perl_call_argv> calls the Perl subroutine specified by the C string
+stored in the C<subname> parameter. It also takes the usual C<flags>
+parameter.  The final parameter, C<argv>, consists of a NULL terminated
+list of C strings to be passed as parameters to the Perl subroutine.
+See I<Using perl_call_argv>.
+
+=back
+
+All the functions return an integer. This is a count of the number of
+items returned by the Perl subroutine. The actual items returned by the
+subroutine are stored on the Perl stack.
+
+As a general rule you should I<always> check the return value from
+these functions.  Even if you are expecting only a particular number of
+values to be returned from the Perl subroutine, there is nothing to
+stop someone from doing something unexpected - don't say you haven't
+been warned.
+
+=head1 FLAG VALUES
+
+The C<flags> parameter in all the I<perl_call_*> functions is a bit mask
+which can consist of any combination of the symbols defined below,
+OR'ed together.
+
+
+=head2  G_SCALAR
+
+Calls the Perl subroutine in a scalar context.  This is the default
+context flag setting for all the I<perl_call_*> functions.
+
+This flag has 2 effects
+
+=over 5
+
+=item 1.
+
+it indicates to the subroutine being called that it is executing in a
+scalar context (if it executes I<wantarray> the result will be false).
 
-I<perl_call_sv> takes two parameters, the first is an SV*. This allows you to 
-specify the Perl sub to be called either as a C string (which has first been 
-converted to an SV) or a reference to a 
-sub. Example 7, shows you how you can make use of I<perl_call_sv>.
-The second parameter, C<flags>, is a general purpose option command. 
-This parameter is common to all the I<perl_call_*> functions. 
-It is discussed in the next section.
 
-The function, I<perl_call_pv>, is similar as I<perl_call_sv> except it 
-expects it's first parameter has to be a C char* which identifies the Perl 
-sub you want to call, e.g. C<perl_call_pv("fred", 0)>.
+=item 2.
+
+it ensures that only a scalar is actually returned from the subroutine.
+The subroutine can, of course,  ignore the I<wantarray> and return a
+list anyway. If so, then only the last element of the list will be
+returned.
+
+=back
+
+The value returned by the I<perl_call_*> function indicates how may
+items have been returned by the Perl subroutine - in this case it will
+be either 0 or 1.
 
-The function I<perl_call_method> expects its first argument to contain a 
-blessed reference to a class. Using that reference it looks up and calls C<methname> 
-from that class. See example 9.
+If 0, then you have specified the G_DISCARD flag.
 
-I<perl_call_argv> calls the Perl sub specified by the C<subname> parameter. 
-It also takes the usual C<flags> parameter. 
-The final parameter, C<argv>, consists of a 
-list of C strings to be sent to the Perl sub. See example 8.
+If 1, then the item actually returned by the Perl subroutine will be
+stored on the Perl stack - the section I<Returning a Scalar> shows how
+to access this value on the stack.  Remember that regardless of how
+many items the Perl subroutine returns, only the last one will be
+accessible from the stack - think of the case where only one value is
+returned as being a list with only one element.  Any other items that
+were returned will not exist by the time control returns from the
+I<perl_call_*> function.  The section I<Returning a list in a scalar
+context> shows an example of this behaviour.
 
-All the functions return a number. This is a count of the number of items
-returned by the Perl sub on the stack.
 
-As a general rule you should I<always> check the return value from these 
-functions.
-Even if you are only expecting a particular number of values to be returned 
-from the Perl sub, there is nothing to stop someone from doing something
-unexpected - don't say you havn't been warned.
+=head2 G_ARRAY
 
-=head2 Flag Values
+Calls the Perl subroutine in a list context.
 
-The C<flags> parameter in all the I<perl_call_*> functions consists of any 
-combination of the symbols defined below, OR'ed together.
+As with G_SCALAR, this flag has 2 effects
 
 =over 5
 
-=item  G_SCALAR	
+=item 1.
+
+it indicates to the subroutine being called that it is executing in an
+array context (if it executes I<wantarray> the result will be true).
 
-Calls the Perl sub in a scalar context.
 
-Whatever the Perl sub actually returns, we only want a scalar. If the perl sub 
-does return a scalar, the return value from the I<perl_call_*> function 
-will be 1 or 0. If 1, then the value actually returned by the Perl sub will 
-be contained
-on the top of the stack. 
-If 0, then the sub has probably called I<die> or you have 
-used the G_DISCARD flag.
+=item 2.
 
-If the Perl sub returns a list, the I<perl_call_*> function will still
-only return 1 or 0. If 1, then the number of elements in the list 
-will be stored on top of the stack.
-The actual values of the list will not be accessable. 
+it ensures that all items returned from the subroutine will be
+accessible when control returns from the I<perl_call_*> function.
 
+=back
 
-G_SCALAR is the default flag setting for all the functions.
+The value returned by the I<perl_call_*> function indicates how may
+items have been returned by the Perl subroutine.
 
-=item G_ARRAY	
+If 0, the you have specified the G_DISCARD flag.
 
-Calls the Perl sub in a list context.
+If not 0, then it will be a count of the number of items returned by
+the subroutine. These items will be stored on the Perl stack.  The
+section I<Returning a list of values> gives an example of using the
+G_ARRAY flag and the mechanics of accessing the returned items from the
+Perl stack.
 
-The return code from the I<perl_call_*> functions will indicate how
-many elements of the stack are used to store the array.
+=head2 G_DISCARD
 
-=item G_DISCARD	
+By default, the I<perl_call_*> functions place the items returned from
+by the Perl subroutine on the stack.  If you are not interested in
+these items, then setting this flag will make Perl get rid of them
+automatically for you.  Note that it is still possible to indicate a
+context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
 
-If you are not interested in the values returned by the Perl sub then setting
-this flag will make Perl get rid of them automatically for you. This will take
-precedence to either G_SCALAR or G_ARRAY.
+If you do not set this flag then it is I<very> important that you make
+sure that any temporaries (i.e. parameters passed to the Perl
+subroutine and values returned from the subroutine) are disposed of
+yourself.  The section I<Returning a Scalar> gives details of how to
+explicitly dispose of these temporaries and the section I<Using Perl to
+dispose of temporaries> discusses the specific circumstances where you
+can ignore the problem and let Perl deal with it for you.
 
-If you do 
-not set this flag then you may need to explicitly get rid of temporary values.
-See example 3 for details.
+=head2 G_NOARGS
 
-=item G_NOARGS	
+Whenever a Perl subroutine is called using one of the I<perl_call_*>
+functions, it is assumed by default that parameters are to be passed to
+the subroutine.  If you are not passing any parameters to the Perl
+subroutine, you can save a bit of time by setting this flag.  It has
+the effect of not creating the C<@_> array for the Perl subroutine.
 
-If you are not passing any parameters to the Perl sub, you can save a bit of 
-time by setting this flag. It has the effect of of not creating the C<@_> array 
-for the Perl sub.
+Although the functionality provided by this flag may seem
+straightforward, it should be used only if there is a good reason to do
+so.  The reason for being cautious is that even if you have specified
+the G_NOARGS flag, it is still possible for the Perl subroutine that
+has been called to think that you have passed it parameters.
 
-A point worth noting is that if this flag is specified the Perl sub called can 
-still access an C<@_> array from a previous Perl sub. 
-This functionality can be illustrated with the perl code below
+In fact, what can happen is that the Perl subroutine you have called
+can access the C<@_> array from a previous Perl subroutine.  This will
+occur when the code that is executing the I<perl_call_*> function has
+itself been called from another Perl subroutine. The code below
+illustrates this
 
-	sub fred
-	  { print "@_\n"  }
+    sub fred
+      { print "@_\n"  }
 
-	sub joe
-	  { &fred }
+    sub joe
+      { &fred }
 
-	&joe(1,2,3) ;
+    &joe(1,2,3) ;
 
 This will print
 
-	1 2 3
+    1 2 3
+
+What has happened is that C<fred> accesses the C<@_> array which
+belongs to C<joe>.
 
-What has happened is that C<fred> accesses the C<@_> array which belongs to C<joe>.
 
-=item G_EVAL	
+=head2 G_EVAL	
 
-If the Perl sub you are calling has the ability to terminate 
-abnormally, e.g. by calling I<die> or by not actually existing, and 
-you want to catch this type of event, specify this flag setting. It will put 
-an I<eval { }> around the sub call.
+It is possible for the Perl subroutine you are calling to terminate
+abnormally, e.g. by calling I<die> explicitly or by not actually
+existing.  By default, when either of these of events occurs, the
+process will terminate immediately.  If though, you want to trap this
+type of event, specify the G_EVAL flag.  It will put an I<eval { }>
+around the subroutine call.
 
 Whenever control returns from the I<perl_call_*> function you need to
-check the C<$@> variable as you would in a normal Perl script. 
-See example 6 for details of how to do this.
+check the C<$@> variable as you would in a normal Perl script.
+
+The value returned from the I<perl_call_*> function is dependent on
+what other flags have been specified and whether an error has
+occurred.  Here are all the different cases that can occur
+
+=over 5
+
+=item *
+
+If the I<perl_call_*> function returns normally, then the value
+returned is as specified in the previous sections.
+
+=item *
+
+If G_DISCARD is specified, the return value will always be 0.
+
+=item *
+
+If G_ARRAY is specified I<and> an error has occurred, the return value
+will always be 0.
+
+=item *
 
+If G_SCALAR is specified I<and> an error has occurred, the return value
+will be 1 and the value on the top of the stack will be I<undef>. This
+means that if you have already detected the error by checking C<$@> and
+you want the program to continue, you must remember to pop the I<undef>
+from the stack.
 
 =back
 
+See I<Using G_EVAL> for details of using G_EVAL.
+
+=head2 Determining the Context 
+
+As mentioned above, you can determine the context of the currently
+executing subroutine in Perl with I<wantarray>. The equivalent test can
+be made in C by using the C<GIMME> macro. This will return C<G_SCALAR>
+if you have been called in a scalar context and C<G_ARRAY> if in an
+array context. An example of using the C<GIMME> macro is shown in
+section I<Using GIMME>.
+
+=head1 KNOWN PROBLEMS
+
+This section outlines all known problems that exist in the
+I<perl_call_*> functions.
+
+=over 5
+
+=item 1.
+
+If you are intending to make use of both the G_EVAL and G_SCALAR flags
+in your code, use a version of Perl greater than 5.000.  There is a bug
+in version 5.000 of Perl which means that the combination of these two
+flags will not work as described in the section I<FLAG VALUES>.
+
+Specifically, if the two flags are used when calling a subroutine and
+that subroutine does not call I<die>, the value returned by
+I<perl_call_*> will be wrong.
+
+
+=item 2.
+
+In Perl 5.000 and 5.001 there is a problem with using I<perl_call_*> if
+the Perl sub you are calling attempts to trap a I<die>.
+
+The symptom of this problem is that the called Perl sub will continue
+to completion, but whenever it attempts to pass control back to the
+XSUB, the program will immediately terminate.
+
+For example, say you want to call this Perl sub
+
+    sub fred
+    {
+        eval { die "Fatal Error" ; }
+        print "Trapped error: $@\n" 
+            if $@ ;
+    }
+
+via this XSUB
+
+    void
+    Call_fred()
+        CODE:
+        PUSHMARK(sp) ;
+        perl_call_pv("fred", G_DISCARD|G_NOARGS) ;
+        fprintf(stderr, "back in Call_fred\n") ;
+
+When C<Call_fred> is executed it will print
+
+    Trapped error: Fatal Error
+
+As control never returns to C<Call_fred>, the C<"back in Call_fred">
+string will not get printed.
+
+To work around this problem, you can either upgrade to Perl 5.002 (or
+later), or use the G_EVAL flag with I<perl_call_*> as shown below
+
+    void
+    Call_fred()
+        CODE:
+        PUSHMARK(sp) ;
+        perl_call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ;
+        fprintf(stderr, "back in Call_fred\n") ;
+
+=back
+
+
 
 =head1 EXAMPLES
 
 Enough of the definition talk, let's have a few examples.
 
-Perl provides many macros to assist in accessing the Perl stack. 
-These macros should always be used when interfacing to Perl internals.
-Hopefully this should make the code less vulnerable to changes made to
-Perl in the future.
-
-Another point worth noting is that in the first series of examples I have 
-only made use of the I<perl_call_pv> function. 
-This has only been done to ease you into the 
-topic. Wherever possible, if the choice is between using I<perl_call_pv> 
-and I<perl_call_sv>, I would always try to use I<perl_call_sv>.
+Perl provides many macros to assist in accessing the Perl stack.
+Wherever possible, these macros should always be used when interfacing
+to Perl internals.  Hopefully this should make the code less vulnerable
+to any changes made to Perl in the future.
 
-The code for these examples is stored in the file F<perlcall.tar>. 
-(Once this document settles down, all the example code will be available in the file).
+Another point worth noting is that in the first series of examples I
+have made use of only the I<perl_call_pv> function.  This has been done
+to keep the code simpler and ease you into the topic.  Wherever
+possible, if the choice is between using I<perl_call_pv> and
+I<perl_call_sv>, you should always try to use I<perl_call_sv>.  See
+I<Using perl_call_sv> for details.
 
-=head2 Example1: No Parameters, Nothing returned
+=head2 No Parameters, Nothing returned
 
-This first trivial example will call a Perl sub, I<PrintUID>, to print 
-out the UID of the process. 
+This first trivial example will call a Perl subroutine, I<PrintUID>, to
+print out the UID of the process.
 
     sub PrintUID
     {
         print "UID is $<\n" ;
     }
 
-and here is the C to call it
+and here is a C function to call it
 
-    void
+    static void
     call_PrintUID()
     {
-	dSP ;
+        dSP ;
 
-	PUSHMARK(sp) ;
+        PUSHMARK(sp) ;
         perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
     }
 
-Simple, eh. 
+Simple, eh.
 
-A few points to note about this example. 
+A few points to note about this example.
 
 =over 5
 
-=item 1. 
+=item 1.
 
-We aren't passing any parameters to I<PrintUID> so G_NOARGS
-can be specified.
+Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in
+the next example.
 
 =item 2.
 
-Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in the next
-example.
+We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
+specified.
 
-=item 3. 
+=item 3.
 
 We aren't interested in anything returned from I<PrintUID>, so
 G_DISCARD is specified. Even if I<PrintUID> was changed to actually
 return some value(s), having specified G_DISCARD will mean that they
 will be wiped by the time control returns from I<perl_call_pv>.
 
-=item 4. 
+=item 4.
 
-Because we specified G_DISCARD, it is not necessary to check 
-the value returned from I<perl_call_sv>. It will always be 0.
+As I<perl_call_pv> is being used, the Perl subroutine is specified as a
+C string. In this case the subroutine name has been 'hard-wired' into the
+code.
 
 =item 5.
 
-As I<perl_call_pv> is being used, the Perl sub is specified as a C string.
+Because we specified G_DISCARD, it is not necessary to check the value
+returned from I<perl_call_pv>. It will always be 0.
 
 =back
 
-=head2 Example 2: Passing Parameters
+=head2 Passing Parameters
 
-Now let's make a slightly more complex example. This time we want 
-to call a Perl sub
-which will take 2 parameters - a string (C<$s>) and an integer (C<$n>). 
-The sub will simply print the first C<$n> characters of the string.
+Now let's make a slightly more complex example. This time we want to
+call a Perl subroutine, C<LeftString>, which will take 2 parameters - a
+string (C<$s>) and an integer (C<$n>).  The subroutine will simply
+print the first C<$n> characters of the string.
 
-So the Perl sub would look like this
+So the Perl subroutine would look like this
 
     sub LeftString
     {
@@ -277,75 +476,81 @@ The C function required to call I<LeftString> would look like this.
         perl_call_pv("LeftString", G_DISCARD);
     }
 
-
 Here are a few notes on the C function I<call_LeftString>.
 
 =over 5
 
-=item 1. 
-
-The only flag specified this time is G_DISCARD. As we are passing 2 
-parameters to the Perl sub this time, we have not specified G_NOARGS.
-
-=item 2. 
+=item 1.
 
-Parameters are passed to the Perl sub using the Perl stack.
-This is the purpose of the code beginning with the line C<dSP> and ending
-with the line C<PUTBACK>.
+Parameters are passed to the Perl subroutine using the Perl stack.
+This is the purpose of the code beginning with the line C<dSP> and
+ending with the line C<PUTBACK>.
 
 
-=item 3.
+=item 2.
 
 If you are going to put something onto the Perl stack, you need to know
-where to put it. This is the purpose of the macro C<dSP> -
-it declares and initialises a local copy of the Perl stack pointer.
+where to put it. This is the purpose of the macro C<dSP> - it declares
+and initializes a I<local> copy of the Perl stack pointer.
 
 All the other macros which will be used in this example require you to
-have used this macro. 
+have used this macro.
 
-If you are calling a Perl sub directly from an XSUB function, it is 
-not necessary to explicitly use the C<dSP> macro - it will be declared for you.
+The exception to this rule is if you are calling a Perl subroutine
+directly from an XSUB function. In this case it is not necessary to
+explicitly use the C<dSP> macro - it will be declared for you
+automatically.
 
-=item 4.
+=item 3.
 
 Any parameters to be pushed onto the stack should be bracketed by the
-C<PUSHMARK> and C<PUTBACK> macros. 
-The purpose of these two macros, in this context, is to automatically count
-the number of parameters you are pushing. Then whenever Perl is creating
-the C<@_> array for the sub, it knows how big to make it.
-
-The C<PUSHMARK> macro tells Perl to make a mental note of the current stack
-pointer. Even if you aren't passing any parameters (like in Example 1) you must 
-still call the C<PUSHMARK> macro before you can call any of 
-the I<perl_call_*> functions - Perl still needs to know that there are 
-no parameters.
-
-The C<PUTBACK> macro sets the global copy of the stack pointer to be the
-same as our local copy. If we didn't do this I<perl_call_pv> wouldn't
-know where the two parameters we pushed were - remember that up to now
-all the stack pointer manipulation we have done is with our local copy,
-I<not> the global copy.
+C<PUSHMARK> and C<PUTBACK> macros.  The purpose of these two macros, in
+this context, is to automatically count the number of parameters you
+are pushing. Then whenever Perl is creating the C<@_> array for the
+subroutine, it knows how big to make it.
+
+The C<PUSHMARK> macro tells Perl to make a mental note of the current
+stack pointer. Even if you aren't passing any parameters (like the
+example shown in the section I<No Parameters, Nothing returned>) you
+must still call the C<PUSHMARK> macro before you can call any of the
+I<perl_call_*> functions - Perl still needs to know that there are no
+parameters.
+
+The C<PUTBACK> macro sets the global copy of the stack pointer to be
+the same as our local copy. If we didn't do this I<perl_call_pv>
+wouldn't know where the two parameters we pushed were - remember that
+up to now all the stack pointer manipulation we have done is with our
+local copy, I<not> the global copy.
+
+=item 4.
+
+The only flag specified this time is G_DISCARD. Since we are passing 2
+parameters to the Perl subroutine this time, we have not specified
+G_NOARGS.
 
 =item 5.
 
 Next, we come to XPUSHs. This is where the parameters actually get
-pushed onto the stack. In this case we are pushing a string and an integer.
+pushed onto the stack. In this case we are pushing a string and an
+integer.
 
-See the section I<XSUB's AND  THE ARGUMENT STACK> in L<perlguts> for
-details on how the XPUSH macros work.
+See the section L<perlguts/"XSUB'S and the Argument Stack"> for details
+on how the XPUSH macros work.
 
 =item 6.
 
-Finally, I<LeftString> can now be called via the I<perl_call_pv> function.
+Finally, I<LeftString> can now be called via the I<perl_call_pv>
+function.
 
 =back
 
-=head2 Example 3: Returning a Scalar
+=head2 Returning a Scalar
 
-Now for an example of dealing with the values returned from a Perl sub.
+Now for an example of dealing with the items returned from a Perl
+subroutine.
 
-Here is a Perl sub, I<Adder>,  which takes 2 integer parameters and simply 
-returns their sum.
+Here is a Perl subroutine, I<Adder>,  which takes 2 integer parameters
+and simply returns their sum.
 
     sub Adder
     {
@@ -353,8 +558,8 @@ returns their sum.
         $a + $b ;
     }
 
-As we are now concerned with the return value from I<Adder>, the C function
-is now a bit more complex.
+Since we are now concerned with the return value from I<Adder>, the C
+function required to call it is now a bit more complex.
 
     static void
     call_Adder(a, b)
@@ -376,107 +581,113 @@ is now a bit more complex.
 
         SPAGAIN ;
 
-	if (count != 1)
-	    croak("Big trouble\n") ;
+        if (count != 1)
+            croak("Big trouble\n") ;
 
-	printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
+        printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
 
         PUTBACK ;
         FREETMPS ;
         LEAVE ;
     }
 
-
 Points to note this time are
 
 =over 5
 
 =item 1. 
 
-The only flag specified this time was G_SCALAR. That means the @_ array
-will be created and that the value returned by I<Adder> will still
-exist after the call to I<perl_call_pv>.
+The only flag specified this time was G_SCALAR. That means the C<@_>
+array will be created and that the value returned by I<Adder> will
+still exist after the call to I<perl_call_pv>.
 
 
 
 =item 2.
 
-Because we are interested in what is returned from I<Adder> we cannot specify
-G_DISCARD. This means that we will have to tidy up the Perl stack and dispose
-of any temporary values ourselves. This is the purpose of 
+Because we are interested in what is returned from I<Adder> we cannot
+specify G_DISCARD. This means that we will have to tidy up the Perl
+stack and dispose of any temporary values ourselves. This is the
+purpose of
 
-	ENTER ;
-	SAVETMPS ;
+    ENTER ;
+    SAVETMPS ;
 
 at the start of the function, and
 
-	FREETMPS ;
-	LEAVE ;
+    FREETMPS ;
+    LEAVE ;
+
+at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
+temporaries we create.  This means that the temporaries we get rid of
+will be limited to those which were created after these calls.
 
-at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any 
-temporaries we create. 
-This means that the temporaries we get rid of will be limited to those which
-were created after these calls.
+The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
+the Perl subroutine, plus it will also dump the mortal SV's we have
+created.  Having C<ENTER>/C<SAVETMPS> at the beginning of the code
+makes sure that no other mortals are destroyed.
 
-The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by the Perl 
-sub, plus it will also dump the mortal SV's we created. 
-Having C<ENTER>/C<SAVETMPS> at the beginning
-of the code makes sure that no other mortals are destroyed.
+Think of these macros as working a bit like using C<{> and C<}> in Perl
+to limit the scope of local variables.
+
+See the section I<Using Perl to dispose of temporaries> for details of
+an alternative to using these macros.
 
 =item 3.
 
 The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
 stack pointer. This is necessary because it is possible that the memory
-allocated to the Perl stack has been re-allocated whilst in the I<perl_call_pv>
-call.
+allocated to the Perl stack has been re-allocated whilst in the
+I<perl_call_pv> call.
 
-If you are making use of the Perl stack pointer in your code you must always
-refresh the your local copy using SPAGAIN whenever you make use of
+If you are making use of the Perl stack pointer in your code you must
+always refresh the your local copy using SPAGAIN whenever you make use
 of the I<perl_call_*> functions or any other Perl internal function.
 
-=item 4. 
+=item 4.
 
-Although only a single value was expected to be returned from I<Adder>, it is
-still good practice to check the return code from I<perl_call_pv> anyway.
+Although only a single value was expected to be returned from I<Adder>,
+it is still good practice to check the return code from I<perl_call_pv>
+anyway.
 
-Expecting a single value is not quite the same as knowing that there will
-be one. If someone modified I<Adder> to return a list and we didn't check
-for that possibility and take appropriate action the Perl stack would end 
-up in an inconsistant state. That is something you I<really> don't want
-to ever happen.
+Expecting a single value is not quite the same as knowing that there
+will be one. If someone modified I<Adder> to return a list and we
+didn't check for that possibility and take appropriate action the Perl
+stack would end up in an inconsistent state. That is something you
+I<really> don't want to ever happen.
 
 =item 5.
 
-The C<POPi> macro is used here to pop the return value from the stack. In this
-case we wanted an integer, so C<POPi> was used.
+The C<POPi> macro is used here to pop the return value from the stack.
+In this case we wanted an integer, so C<POPi> was used.
 
 
-Here is the complete list of POP macros available, along with the types they 
-return.
+Here is the complete list of POP macros available, along with the types
+they return.
 
-	POPs	SV
-	POPp	pointer
-	POPn	double
-	POPi	integer
-	POPl	long
+    POPs	SV
+    POPp	pointer
+    POPn	double
+    POPi	integer
+    POPl	long
 
 =item 6.
 
-The final C<PUTBACK> is used to leave the Perl stack in a consistant state 
-before exiting the function. This is
-necessary because when we popped the return value from the stack with C<POPi> it
-only updated our local copy of the stack pointer. Remember, C<PUTBACK> sets the
-global stack pointer to be the same as our local copy.
+The final C<PUTBACK> is used to leave the Perl stack in a consistent
+state before exiting the function.  This is necessary because when we
+popped the return value from the stack with C<POPi> it updated only our
+local copy of the stack pointer.  Remember, C<PUTBACK> sets the global
+stack pointer to be the same as our local copy.
 
 =back
 
 
-=head2 Example 4: Returning a list of values
+=head2 Returning a list of values
 
-Now, let's extend the previous example to return both the sum of the parameters 
-and the difference.
+Now, let's extend the previous example to return both the sum of the
+parameters and the difference.
 
-Here is the Perl sub
+Here is the Perl subroutine
 
     sub AddSubtract
     {
@@ -484,7 +695,6 @@ Here is the Perl sub
        ($a+$b, $a-$b) ;
     }
 
-
 and this is the C function
 
     static void
@@ -507,17 +717,25 @@ and this is the C function
 
         SPAGAIN ;
 
-	if (count != 2)
-	    croak("Big trouble\n") ;
+        if (count != 2)
+            croak("Big trouble\n") ;
 
-	printf ("%d - %d = %d\n", a, b, POPi) ;
-	printf ("%d + %d = %d\n", a, b, POPi) ;
+        printf ("%d - %d = %d\n", a, b, POPi) ;
+        printf ("%d + %d = %d\n", a, b, POPi) ;
 
         PUTBACK ;
         FREETMPS ;
         LEAVE ;
     }
 
+If I<call_AddSubtract> is called like this
+
+    call_AddSubtract(7, 4) ;
+
+then here is the output
+
+    7 - 4 = 3
+    7 + 4 = 11
 
 Notes
 
@@ -525,22 +743,77 @@ Notes
 
 =item 1.
 
-We wanted array context, so we used G_ARRAY.
+We wanted array context, so G_ARRAY was used.
 
 =item 2.
 
-Not surprisingly there are 2 POPi's this time  because we were retrieving 2
-values from the stack. The main point to note is that they came off the stack in
-reverse order.
+Not surprisingly C<POPi> is used twice this time because we were
+retrieving 2 values from the stack. The important thing to note is that
+when using the C<POP*> macros they come off the stack in I<reverse>
+order.
 
 =back
 
-=head2 Example 5: Returning Data from Perl via the parameter list
+=head2 Returning a list in a scalar context
+
+Say the Perl subroutine in the previous section was called in a scalar
+context, like this
+
+    static void
+    call_AddSubScalar(a, b)
+    int a ;
+    int b ;
+    {
+        dSP ;
+        int count ;
+        int i ;
+
+        ENTER ;
+        SAVETMPS;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSViv(a)));
+        XPUSHs(sv_2mortal(newSViv(b)));
+        PUTBACK ;
+
+        count = perl_call_pv("AddSubtract", G_SCALAR);
+
+        SPAGAIN ;
+
+        printf ("Items Returned = %d\n", count) ;
+
+        for (i = 1 ; i <= count ; ++i)
+            printf ("Value %d = %d\n", i, POPi) ;
+
+        PUTBACK ;
+        FREETMPS ;
+        LEAVE ;
+    }
+
+The other modification made is that I<call_AddSubScalar> will print the
+number of items returned from the Perl subroutine and their value (for
+simplicity it assumes that they are integer).  So if
+I<call_AddSubScalar> is called
+
+    call_AddSubScalar(7, 4) ;
+
+then the output will be
+
+    Items Returned = 1
+    Value 1 = 3
+
+In this case the main point to note is that only the last item in the
+list returned from the subroutine, I<Adder> actually made it back to
+I<call_AddSubScalar>.
+
+
+=head2 Returning Data from Perl via the parameter list
 
 It is also possible to return values directly via the parameter list -
 whether it is actually desirable to do it is another matter entirely.
 
-The Perl sub, I<Inc>, below takes 2 parameters and increments each.
+The Perl subroutine, I<Inc>, below takes 2 parameters and increments
+each directly.
 
     sub Inc
     {
@@ -574,43 +847,40 @@ and here is a C function to call it.
         count = perl_call_pv("Inc", G_DISCARD);
 
         if (count != 0)
-            croak ("call_Inc : expected 0 return value from 'Inc', got %d\n", count) ;
+            croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
+                   count) ;
 
         printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
         printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
 
     	FREETMPS ;
-	LEAVE ; 
+        LEAVE ;
     }
 
+To be able to access the two parameters that were pushed onto the stack
+after they return from I<perl_call_pv> it is necessary to make a note
+of their addresses - thus the two variables C<sva> and C<svb>.
 
-
-To be able to access the two parameters that were pushed onto the stack 
-after they return from I<perl_call_pv> it is necessary to make a note of
-their addresses - thus the two variables C<sva> and C<svb>. 
-
-The reason this is necessary is that
-the area of the Perl stack which held them
-will very likely have been overwritten by something else by the time control
-returns from I<perl_call_pv>.
+The reason this is necessary is that the area of the Perl stack which
+held them will very likely have been overwritten by something else by
+the time control returns from I<perl_call_pv>.
 
 
 
 
-=head2 Example 6: Using G_EVAL
-
-Now an example using G_EVAL. Below is a Perl sub which computes the 
-difference of its 2 parameters. If this would result in a negative result,
-the sub calls I<die>.
+=head2 Using G_EVAL
 
+Now an example using G_EVAL. Below is a Perl subroutine which computes
+the difference of its 2 parameters. If this would result in a negative
+result, the subroutine calls I<die>.
 
     sub Subtract
     {
-	my ($a, $b) = @_ ;
+        my ($a, $b) = @_ ;
 
         die "death can be fatal\n" if $a < $b ;
 
-	$a - $b ;
+        $a - $b ;
     }
 
 and some C to call it
@@ -622,7 +892,7 @@ and some C to call it
     {
         dSP ;
         int count ;
-	SV * sv ;
+        SV * sv ;
 
         ENTER ;
         SAVETMPS;
@@ -634,32 +904,36 @@ and some C to call it
 
         count = perl_call_pv("Subtract", G_EVAL|G_SCALAR);
 
-	/* Check the eval first */
+        SPAGAIN ;
+
+        /* Check the eval first */
         sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
         if (SvTRUE(sv))
+        {
             printf ("Uh oh - %s\n", SvPV(sv, na)) ;
+            POPs ;
+        }
+        else
+        {
+            if (count != 1)
+               croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
+                        count) ;
 
-        SPAGAIN ;
-
-        if (count != 1)
-            croak ("call_Subtract : expected 1 return value from 'Subtract', got %d\n", count) ;
-
-
-	printf ("%d - %d = %d\n", a, b, POPi) ;
+            printf ("%d - %d = %d\n", a, b, POPi) ;
+        }
 
         PUTBACK ;
         FREETMPS ;
         LEAVE ;
-
     }
 
 If I<call_Subtract> is called thus
 
-	call_Subtract(4, 5)
+    call_Subtract(4, 5)
 
 the following will be printed
 
-	Uh oh - death can be fatal
+    Uh oh - death can be fatal
 
 Notes
 
@@ -667,156 +941,882 @@ Notes
 
 =item 1.
 
-We want to be able to catch the I<die> so we have used the G_EVAL flag.
-Not specifying this flag would mean that the program would terminate.
+We want to be able to catch the I<die> so we have used the G_EVAL
+flag.  Not specifying this flag would mean that the program would
+terminate immediately at the I<die> statement in the subroutine
+I<Subtract>.
 
 =item 2.
 
 The code 
 
-        sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
-        if (SvTRUE(sv))
-            printf ("Uh oh - %s\n", SvPVx(sv, na)) ;
+    sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
+    if (SvTRUE(sv))
+    {
+        printf ("Uh oh - %s\n", SvPVx(sv, na)) ;
+        POPs ;
+    }
 
-is the equivalent of this bit of Perl
+is the direct equivalent of this bit of Perl
 
-	print "Uh oh - $@\n" if $@ ;
+    print "Uh oh - $@\n" if $@ ;
 
+=item 3.
 
+Note that the stack is popped using C<POPs> in the block where
+C<SvTRUE(sv)> is true.  This is necessary because whenever a
+I<perl_call_*> function invoked with G_EVAL|G_SCALAR returns an error,
+the top of the stack holds the value I<undef>. Since we want the
+program to continue after detecting this error, it is essential that
+the stack is tidied up by removing the I<undef>.
 
 =back
 
 
-=head2 Example 7: Using perl_call_sv
+=head2 Using perl_call_sv
 
-In all the previous examples I have 'hard-wried' the name of the Perl sub to
-be called from C. 
-Sometimes though, it is necessary to be able to specify the name
-of the Perl sub from within the Perl script.
+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" ;
-	}
+    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) ;
+    	perl_call_pv(name, G_DISCARD|G_NOARGS) ;
 
-	CallSub("fred") ;
+That is fine as far as it goes. The thing is, the Perl subroutine 
+can be specified only as a string.  For Perl 4 this was adequate,
+but Perl 5 allows references to subroutines and anonymous subroutines.
+This is where I<perl_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<perl_call_sv> instead of I<perl_call_pv>.
+
+    void
+    CallSubSV(name)
+    	SV *	name
+    	CODE:
+    	PUSHMARK(sp) ;
+    	perl_call_sv(name, G_DISCARD|G_NOARGS) ;
 
+Since we are using an SV to call I<fred> the following can all be used
 
-here is a snippet of XSUB which defines I<CallSub>.
+    CallSubSV("fred") ;
+    CallSubSV(\&fred) ;
+    $ref = \&fred ;
+    CallSubSV($ref) ;
+    CallSubSV( sub { print "Hello there\n" } ) ;
 
-	void
-	CallSub(name)
-		char *	name
-		CODE:
-		PUSHMARK(sp) ;
-		perl_call_pv(name, G_DISCARD|G_NOARGS) ;
+As you can see, I<perl_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 to just 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) ;
+    	perl_call_sv(rememberSub, G_DISCARD|G_NOARGS) ;
 
-That is fine as far as it goes. The thing is, it only allows the Perl sub to be
-specified as a string. 
-For perl 4 this was adequate, but Perl 5 allows references to 
-subs and anonymous subs. This is where I<perl_call_sv> is useful.
+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
 
-The code below for I<CallSub> is identical to the previous time except that the
-C<name> parameter is now defined as an SV* and we use I<perl_call_sv> instead of
-I<perl_call_pv>.
+    SaveSub1(\&fred) ;
+    CallSavedSub1() ;
 
-	void
-	CallSub(name)
-		SV*	name
-		CODE:
-		PUSHMARK(sp) ;
-		perl_call_sv(name, G_DISCARD|G_NOARGS) ;
+    SaveSub1( sub { print "Hello there\n" } ) ;
+    CallSavedSub1() ;
 
-As we are using an SV to call I<fred> the following can all be used
+By the time each of the C<SaveSub1> statements above have been executed,
+the SV*'s which corresponded to the parameters will no longer exist.
+Expect an error message from Perl of the form
 
-	CallSub("fred") ;
-	Callsub(\&fred) ;
-	$ref = \&fred ;
-	CallSub($ref) ;
-	CallSub( sub { print "Hello there\n" } ) ;
+    Can't use an undefined value as a subroutine reference at ...
 
-As you can see, I<perl_call_sv> gives you greater flexibility in how you 
-can specify the Perl sub.
+for each of the C<CallSavedSub1> lines.
 
-=head2 Example 8: Using perl_call_argv
+Similarly, with this code 
 
-Here is a Perl sub which prints whatever parameters are passed to it.
+    $ref = \&fred ;
+    SaveSub1($ref) ;
+    $ref = 47 ;
+    CallSavedSub1() ;
 
-	sub PrintList
-	{
-	    my(@list) = @_ ;
+you can expect one of these messages (which you actually get is dependant on 
+the version of Perl you are using) 
 
-	    foreach (@list) { print "$_\n" }
-	}
+    Not a CODE reference at ...
+    Undefined subroutine &main::47 called ...
 
-and here is an example of I<perl_call_argv> which will call I<PrintList>.
+The variable C<$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>. Since we
+saved only a pointer to the original SV in C<SaveSub1>, any changes to
+C<$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.
 
-	call_PrintList
-	{
-	    dSP ;
-	    char * words[] = {"alpha", "beta", "gamma", "delta", NULL } ;
+A similar but more subtle problem is illustrated with this code
 
-	    perl_call_argv("PrintList", words, G_DISCARD) ;
-	}
+    $ref = \&fred ;
+    SaveSub1($ref) ;
+    $ref = \&joe ;
+    CallSavedSub1() ;
 
-Note that it is not necessary to call C<PUSHMARK> in this instance. This is
-because I<perl_call_argv> will do it for you.
+This time whenever C<CallSavedSub1> get 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>.
 
-=head2 Example 9: Using perl_call_method
+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
 
-[This section is under construction]
+    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) ;
+    	perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ;
+
+In order 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 perl_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<perl_call_argv> which will call
+I<PrintList>.
+
+    static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ;
+
+    static void
+    call_PrintList()
+    {
+        dSP ;
+
+        perl_call_argv("PrintList", G_DISCARD, words) ;
+    }
+
+Note that it is not necessary to call C<PUSHMARK> in this instance.
+This is because I<perl_call_argv> will do it for you.
+
+=head2 Using perl_call_method
 
 Consider the following Perl code
 
-	{
-	  package Mine ;
+    {
+        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 just implements 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>, simply prints out 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 = new Mine ('red', 'green', 'blue') ;
+    $a->Display(1) ;
+    PrintID Mine;
 
-	  sub new     { bless [@_] }
-	  sub Display { print $_[0][1], "\n" }
-	}
+will print
 
-	$a = new Mine ('red', 'green', 'blue') ;
-	call_Display($a, 'Display') ;
+    1: green
+    This is Class Mine version 1.0 
 
-The method C<Display> just prints out the first element of the list.
-Here is a XSUB implementation of I<call_Display>.
+Calling a Perl method from C is fairly straightforward. The following
+things are required
 
-	void
-	call_Display(ref, method)
-            SV *    ref
-            char *  method
-            CODE:
-            PUSHMARK(sp);
-            XPUSHs(ref);
-            PUTBACK;
+=over 5
+
+=item *
+
+a reference to the object for a virtual method or the name of the class
+for a static method.
+
+=item *
+
+the name of the method.
+
+=item *
+
+any other parameters specific to the method.
+
+=back
+
+Here is a simple XSUB which illustrates the mechanics of calling both
+the C<PrintID> and C<Display> methods from C.
+
+    void
+    call_Method(ref, method, index)
+        SV *	ref
+        char *	method
+        int		index
+        CODE:
+        PUSHMARK(sp);
+        XPUSHs(ref);
+        XPUSHs(sv_2mortal(newSViv(index))) ;
+        PUTBACK;
+
+        perl_call_method(method, G_DISCARD) ;
+
+    void
+    call_PrintID(class, method)
+        char *	class
+        char *	method
+        CODE:
+        PUSHMARK(sp);
+        XPUSHs(sv_2mortal(newSVpv(class, 0))) ;
+        PUTBACK;
+
+        perl_call_method(method, G_DISCARD) ;
+
+
+So the methods C<PrintID> and C<Display> can be invoked like this
+
+    $a = new Mine ('red', 'green', 'blue') ;
+    call_Method($a, 'Display', 1) ;
+    call_PrintID('Mine', 'PrintID') ;
+
+The only thing to note is that in both the static and virtual methods,
+the method name is not passed via the stack - it is used as the first
+parameter to I<perl_call_method>.
+
+=head2 Using GIMME
+
+Here is a trivial XSUB which prints the context in which it is 
+currently executing.
+
+    void
+    PrintContext()
+        CODE:
+        if (GIMME == G_SCALAR)
+            printf ("Context is Scalar\n") ;
+        else
+            printf ("Context is Array\n") ;
+
+and here is some Perl to test it
+
+    $a = PrintContext ;
+    @a = PrintContext ;
+
+The output from that will be
+
+    Context is Scalar
+    Context is Array
+
+=head2 Using Perl to dispose of temporaries
+
+In the examples given to date, any temporaries created in the callback
+(i.e. parameters passed on the stack to the I<perl_call_*> function or
+values returned via the stack) have been freed by one of these methods
+
+=over 5
+
+=item *
+
+specifying the G_DISCARD flag with I<perl_call_*>.
+
+=item *
+
+explicitly disposed of using the C<ENTER>/C<SAVETMPS> -
+C<FREETMPS>/C<LEAVE> pairing.
+
+=back
+
+There is another method which can be used, namely letting Perl do it
+for you automatically whenever it regains control after the callback
+has terminated.  This is done by simply not using the
+
+    ENTER ;
+    SAVETMPS ;
+    ...
+    FREETMPS ;
+    LEAVE ;
+
+sequence in the callback (and not, of course, specifying the G_DISCARD
+flag).
+
+If you are going to use this method you have to be aware of a possible
+memory leak which can arise under very specific circumstances.  To
+explain these circumstances you need to know a bit about the flow of
+control between Perl and the callback routine.
+
+The examples given at the start of the document (an error handler and
+an event driven program) are typical of the two main sorts of flow
+control that you are likely to encounter with callbacks.  There is a
+very important distinction between them, so pay attention.
+
+In the first example, an error handler, the flow of control could be as
+follows.  You have created an interface to an external library.
+Control can reach the external library like this
+
+    perl --> XSUB --> external library
+
+Whilst control is in the library, an error condition occurs. You have
+previously set up a Perl callback to handle this situation, so it will
+get executed. Once the callback has finished, control will drop back to
+Perl again.  Here is what the flow of control will be like in that
+situation
+
+    perl --> XSUB --> external library
+                      ...
+                      error occurs
+                      ...
+                      external library --> perl_call --> perl
+                                                          |
+    perl <-- XSUB <-- external library <-- perl_call <----+
+
+After processing of the error using I<perl_call_*> is completed,
+control reverts back to Perl more or less immediately.
+
+In the diagram, the further right you go the more deeply nested the
+scope is.  It is only when control is back with perl on the extreme
+left of the diagram that you will have dropped back to the enclosing
+scope and any temporaries you have left hanging around will be freed.
+
+In the second example, an event driven program, the flow of control
+will be more like this
+
+    perl --> XSUB --> event handler
+                      ...
+                      event handler --> perl_call --> perl 
+                                                       |
+                      event handler <-- perl_call --<--+
+                      ...
+                      event handler --> perl_call --> perl 
+                                                       |
+                      event handler <-- perl_call --<--+
+                      ...
+                      event handler --> perl_call --> perl 
+                                                       |
+                      event handler <-- perl_call --<--+
+
+In this case the flow of control can consist of only the repeated
+sequence
+
+    event handler --> perl_call --> perl
+
+for the practically the complete duration of the program.  This means
+that control may I<never> drop back to the surrounding scope in Perl at
+the extreme left.
+
+So what is the big problem? Well, if you are expecting Perl to tidy up
+those temporaries for you, you might be in for a long wait.  For Perl
+to actually dispose of your temporaries, control must drop back to the
+enclosing scope at some stage.  In the event driven scenario that may
+never happen.  This means that as time goes on, your program will
+create more and more temporaries, none of which will ever be freed. As
+each of these temporaries consumes some memory your program will
+eventually consume all the available memory in your system - kapow!
+
+So here is the bottom line - if you are sure that control will revert
+back to the enclosing Perl scope fairly quickly after the end of your
+callback, then it isn't absolutely necessary to explicitly dispose of
+any temporaries you may have created. Mind you, if you are at all
+uncertain about what to do, it doesn't do any harm to tidy up anyway.
+
+
+=head2 Strategies for storing Callback Context Information
+
+
+Potentially one of the trickiest problems to overcome when designing a
+callback interface can be figuring out how to store the mapping between
+the C callback function and the Perl equivalent.
+
+To help understand why this can be a real problem first consider how a
+callback is set up in an all C environment.  Typically a C API will
+provide a function to register a callback.  This will expect a pointer
+to a function as one of its parameters.  Below is a call to a
+hypothetical function C<register_fatal> which registers the C function
+to get called when a fatal error occurs.
+
+    register_fatal(cb1) ;
+
+The single parameter C<cb1> is a pointer to a function, so you must
+have defined C<cb1> in your code, say something like this
+
+    static void
+    cb1()
+    {
+        printf ("Fatal Error\n") ;
+        exit(1) ;
+    }
+
+Now change that to call a Perl subroutine instead
+
+    static SV * callback = (SV*)NULL;
+
+    static void
+    cb1()
+    {
+        dSP ;
+
+        PUSHMARK(sp) ;
+
+        /* Call the Perl sub to process the callback */
+        perl_call_sv(callback, G_DISCARD) ;
+    }
+
+
+    void
+    register_fatal(fn)
+        SV *	fn
+        CODE:
+        /* Remember the Perl sub */
+        if (callback == (SV*)NULL)
+            callback = newSVsv(fn) ;
+        else
+            SvSetSV(callback, fn) ;
+
+        /* register the callback with the external library */
+        register_fatal(cb1) ;
+
+where the Perl equivalent of C<register_fatal> and the callback it
+registers, C<pcb1>, might look like this
+
+    # Register the sub pcb1
+    register_fatal(\&pcb1) ;
+
+    sub pcb1
+    {
+        die "I'm dying...\n" ;
+    }
+
+The mapping between the C callback and the Perl equivalent is stored in
+the global variable C<callback>.
+
+This will be adequate if you ever need to have only 1 callback
+registered at any time. An example could be an error handler like the
+code sketched out above. Remember though, repeated calls to
+C<register_fatal> will replace the previously registered callback
+function with the new one.
+
+Say for example you want to interface to a library which allows asynchronous
+file i/o.  In this case you may be able to register a callback whenever
+a read operation has completed. To be of any use we want to be able to
+call separate Perl subroutines for each file that is opened.  As it
+stands, the error handler example above would not be adequate as it
+allows only a single callback to be defined at any time. What we
+require is a means of storing the mapping between the opened file and
+the Perl subroutine we want to be called for that file.
+
+Say the i/o library has a function C<asynch_read> which associates a C
+function C<ProcessRead> with a file handle C<fh> - this assumes that it
+has also provided some routine to open the file and so obtain the file
+handle.
+
+    asynch_read(fh, ProcessRead)
+
+This may expect the C I<ProcessRead> function of this form
+
+    void
+    ProcessRead(fh, buffer)
+    int	fh ;
+    char *	buffer ;
+    {
+         ... 
+    }
+
+To provide a Perl interface to this library we need to be able to map
+between the C<fh> parameter and the Perl subroutine we want called.  A
+hash is a convenient mechanism for storing this mapping.  The code
+below shows a possible implementation
+
+    static HV * Mapping = (HV*)NULL ;
 
-            perl_call_method(method, G_DISCARD) ;
+    void
+    asynch_read(fh, callback)
+        int	fh
+        SV *	callback
+        CODE:
+        /* If the hash doesn't already exist, create it */
+        if (Mapping == (HV*)NULL)
+            Mapping = newHV() ;
+
+        /* Save the fh -> callback mapping */
+        hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ;
+
+        /* Register with the C Library */
+        asynch_read(fh, asynch_read_if) ;
+
+and C<asynch_read_if> could look like this
+
+    static void
+    asynch_read_if(fh, buffer)
+    int	fh ;
+    char *	buffer ;
+    {
+        dSP ;
+        SV ** sv ;
+
+        /* Get the callback associated with fh */
+        sv =  hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE) ;
+        if (sv == (SV**)NULL)
+            croak("Internal error...\n") ;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSViv(fh))) ;
+        XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
+        PUTBACK ;
+
+        /* Call the Perl sub */
+        perl_call_sv(*sv, G_DISCARD) ;
+    }
+
+For completeness, here is C<asynch_close>.  This shows how to remove
+the entry from the hash C<Mapping>.
+
+    void
+    asynch_close(fh)
+        int	fh
+        CODE:
+        /* Remove the entry from the hash */
+        (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ;
 
+        /* Now call the real asynch_close */
+        asynch_close(fh) ;
 
+So the Perl interface would look like this
+
+    sub callback1
+    {
+        my($handle, $buffer) = @_ ;
+    }
 
+    # Register the Perl callback
+    asynch_read($fh, \&callback1) ;
 
-=head2 Strategies for storing Context Information
+    asynch_close($fh) ;
+
+The mapping between the C callback and Perl is stored in the global
+hash C<Mapping> this time. Using a hash has the distinct advantage that
+it allows an unlimited number of callbacks to be registered.
+
+What if the interface provided by the C callback doesn't contain a
+parameter which allows the file handle to Perl subroutine mapping?  Say
+in the asynchronous i/o package, the callback function gets passed only
+the C<buffer> parameter like this
+
+    void
+    ProcessRead(buffer)
+    char *	buffer ;
+    {
+        ...
+    }
 
-[This section is under construction]
+Without the file handle there is no straightforward way to map from the
+C callback to the Perl subroutine.
 
-One of the trickiest problems to overcome when designing a callback interface 
-is figuring 
-out how to store the mapping between the C callback functions and the 
-Perl equivalent.
+In this case a possible way around this problem is to pre-define a
+series of C functions to act as the interface to Perl, thus
+
+    #define MAX_CB		3
+    #define NULL_HANDLE	-1
+    typedef void (*FnMap)() ;
+
+    struct MapStruct {
+        FnMap    Function ;
+        SV *     PerlSub ;
+        int      Handle ;
+      } ;
+
+    static void  fn1() ;
+    static void  fn2() ;
+    static void  fn3() ;
+
+    static struct MapStruct Map [MAX_CB] =
+        {
+            { fn1, NULL, NULL_HANDLE },
+            { fn2, NULL, NULL_HANDLE },
+            { fn3, NULL, NULL_HANDLE }
+        } ;
+
+    static void
+    Pcb(index, buffer)
+    int index ;
+    char * buffer ;
+    {
+        dSP ;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
+        PUTBACK ;
+
+        /* Call the Perl sub */
+        perl_call_sv(Map[index].PerlSub, G_DISCARD) ;
+    }
+
+    static void
+    fn1(buffer)
+    char * buffer ;
+    {
+        Pcb(0, buffer) ;
+    }
+
+    static void
+    fn2(buffer)
+    char * buffer ;
+    {
+        Pcb(1, buffer) ;
+    }
+
+    static void
+    fn3(buffer)
+    char * buffer ;
+    {
+        Pcb(2, buffer) ;
+    }
+
+    void
+    array_asynch_read(fh, callback)
+        int		fh
+        SV *	callback
+        CODE:
+        int index ;
+        int null_index = MAX_CB ;
+
+        /* Find the same handle or an empty entry */
+        for (index = 0 ; index < MAX_CB ; ++index)
+        {
+            if (Map[index].Handle == fh)
+                break ;
+
+            if (Map[index].Handle == NULL_HANDLE)
+                null_index = index ;
+        }
+
+        if (index == MAX_CB && null_index == MAX_CB)
+            croak ("Too many callback functions registered\n") ;
+
+        if (index == MAX_CB)
+            index = null_index ;
+
+        /* Save the file handle */
+        Map[index].Handle = fh ;
+
+        /* Remember the Perl sub */
+        if (Map[index].PerlSub == (SV*)NULL)
+            Map[index].PerlSub = newSVsv(callback) ;
+        else
+            SvSetSV(Map[index].PerlSub, callback) ;
+
+        asynch_read(fh, Map[index].Function) ;
+
+    void
+    array_asynch_close(fh)
+        int	fh
+        CODE:
+        int index ;
+
+        /* Find the file handle */
+        for (index = 0; index < MAX_CB ; ++ index)
+            if (Map[index].Handle == fh)
+                break ;
+
+        if (index == MAX_CB)
+            croak ("could not close fh %d\n", fh) ;
+
+        Map[index].Handle = NULL_HANDLE ;
+        SvREFCNT_dec(Map[index].PerlSub) ;
+        Map[index].PerlSub = (SV*)NULL ;
+
+        asynch_close(fh) ;
+
+In this case the functions C<fn1>, C<fn2> and C<fn3> are used to
+remember the Perl subroutine to be called. Each of the functions holds
+a separate hard-wired index which is used in the function C<Pcb> to
+access the C<Map> array and actually call the Perl subroutine.
+
+There are some obvious disadvantages with this technique.
+
+Firstly, the code is considerably more complex than with the previous
+example.
+
+Secondly, there is a hard-wired limit (in this case 3) to the number of
+callbacks that can exist simultaneously. The only way to increase the
+limit is by modifying the code to add more functions and then
+re-compiling.  None the less, as long as the number of functions is
+chosen with some care, it is still a workable solution and in some
+cases is the only one available.
+
+To summarize, here are a number of possible methods for you to consider
+for storing the mapping between C and the Perl callback
+
+=over 5
+
+=item 1. Ignore the problem - Allow only 1 callback
+
+For a lot of situations, like interfacing to an error handler, this may
+be a perfectly adequate solution.
+
+=item 2. Create a sequence of callbacks - hard wired limit
+
+If it is impossible to tell from the parameters passed back from the C
+callback what the context is, then you may need to create a sequence of C
+callback interface functions, and store pointers to each in an array.
+
+=item 3. Use a parameter to map to the Perl callback
+
+A hash is an ideal mechanism to store the mapping between C and Perl.
+
+=back
 
-Consider the following example.
 
 =head2 Alternate Stack Manipulation
 
-[This section is under construction]
 
-Although I have only made use of the POP* macros to access values returned 
-from Perl subs, it is also possible to bypass these macros and read the 
-stack directly.
+Although I have made use of only the C<POP*> macros to access values
+returned from Perl subroutines, it is also possible to bypass these
+macros and read the stack using the C<ST> macro (See L<perlapi> for a
+full description of the C<ST> macro).
+
+Most of the time the C<POP*> macros should be adequate, the main
+problem with them is that they force you to process the returned values
+in sequence. This may not be the most suitable way to process the
+values in some cases. What we want is to be able to access the stack in
+a random order. The C<ST> macro as used when coding an XSUB is ideal
+for this purpose.
+
+The code below is the example given in the section I<Returning a list
+of values> recoded to use C<ST> instead of C<POP*>.
+
+    static void
+    call_AddSubtract2(a, b)
+    int a ;
+    int b ;
+    {
+        dSP ;
+        I32 ax ;
+        int count ;
+
+        ENTER ;
+        SAVETMPS;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSViv(a)));
+        XPUSHs(sv_2mortal(newSViv(b)));
+        PUTBACK ;
+
+        count = perl_call_pv("AddSubtract", G_ARRAY);
+
+        SPAGAIN ;
+        sp -= count ;
+        ax = (sp - stack_base) + 1 ;
+
+        if (count != 2)
+            croak("Big trouble\n") ;
 
-The code below is example 4 recoded to 
+        printf ("%d + %d = %d\n", a, b, SvIV(ST(0))) ;
+        printf ("%d - %d = %d\n", a, b, SvIV(ST(1))) ;
+
+        PUTBACK ;
+        FREETMPS ;
+        LEAVE ;
+    }
+
+Notes
+
+=over 5
+
+=item 1.
+
+Notice that it was necessary to define the variable C<ax>.  This is
+because the C<ST> macro expects it to exist.  If we were in an XSUB it
+would not be necessary to define C<ax> as it is already defined for
+you.
+
+=item 2.
+
+The code
+
+        SPAGAIN ;
+        sp -= count ;
+        ax = (sp - stack_base) + 1 ;
+
+sets the stack up so that we can use the C<ST> macro.
+
+=item 3.
+
+Unlike the original coding of this example, the returned
+values are not accessed in reverse order.  So C<ST(0)> refers to the
+first value returned by the Perl subroutine and C<ST(count-1)> 
+refers to the last.
+
+=back
 
 =head1 SEE ALSO
 
@@ -826,13 +1826,11 @@ L<perlapi>, L<perlguts>, L<perlembed>
 
 Paul Marquess <pmarquess@bfsec.bt.co.uk>
 
-Special thanks to the following people who assisted in the creation of the 
-document.
+Special thanks to the following people who assisted in the creation of
+the document.
 
-Jeff Okamoto, Tim Bunce.
+Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem and Larry Wall. 
 
 =head1 DATE
 
-Version 0.4, 17th October 1994
-
-
+Version 1.1, 17th May 1995