Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 2001 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perlcall.1 b/upstream/mageia-cauldron/man1/perlcall.1
new file mode 100644
index 00000000..8c1da949
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlcall.1
@@ -0,0 +1,2001 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLCALL 1"
+.TH PERLCALL 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perlcall \- Perl calling conventions from C
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The purpose of this document is to show you how to call Perl subroutines
+directly from C, i.e., how to write \fIcallbacks\fR.
+.PP
+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.
+.PP
+Examples where callbacks are necessary include
+.IP \(bu 5
+An Error Handler
+.Sp
+You have created an XSUB interface to an application's C API.
+.Sp
+A fairly common feature in applications is to allow you to define a C
+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.
+.IP \(bu 5
+An Event-Driven Program
+.Sp
+The classic example of where callbacks are used is when writing an
+event driven program, such as for an X11 application.  In this case
+you 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.
+.PP
+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
+perlembed.
+.PP
+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\-\-perlxs
+and perlguts.
+.SH "THE CALL_ FUNCTIONS"
+.IX Header "THE CALL_ FUNCTIONS"
+Although this stuff is easier to explain using examples, you first need
+be aware of a few important definitions.
+.PP
+Perl has a number of C functions that allow you to call Perl
+subroutines.  They are
+.PP
+.Vb 4
+\&    I32 call_sv(SV* sv, I32 flags);
+\&    I32 call_pv(char *subname, I32 flags);
+\&    I32 call_method(char *methname, I32 flags);
+\&    I32 call_argv(char *subname, I32 flags, char **argv);
+.Ve
+.PP
+The key function is \fIcall_sv\fR.  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 \fIcall_sv\fR
+to invoke the Perl subroutine.
+.PP
+All the \fIcall_*\fR functions have a \f(CW\*(C`flags\*(C'\fR 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 "FLAG VALUES".
+.PP
+Each of the functions will now be discussed in turn.
+.IP call_sv 5
+.IX Item "call_sv"
+\&\fIcall_sv\fR takes two parameters. The first, \f(CW\*(C`sv\*(C'\fR, 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, "Using call_sv", shows how you can make
+use of \fIcall_sv\fR.
+.IP call_pv 5
+.IX Item "call_pv"
+The function, \fIcall_pv\fR, is similar to \fIcall_sv\fR except it
+expects its first parameter to be a C char* which identifies the Perl
+subroutine you want to call, e.g., \f(CW\*(C`call_pv("fred", 0)\*(C'\fR.  If the
+subroutine you want to call is in another package, just include the
+package name in the string, e.g., \f(CW"pkg::fred"\fR.
+.IP call_method 5
+.IX Item "call_method"
+The function \fIcall_method\fR is used to call a method from a Perl
+class.  The parameter \f(CW\*(C`methname\*(C'\fR 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 perlobj for more information on
+static and virtual methods and "Using call_method" for an example
+of using \fIcall_method\fR.
+.IP call_argv 5
+.IX Item "call_argv"
+\&\fIcall_argv\fR calls the Perl subroutine specified by the C string
+stored in the \f(CW\*(C`subname\*(C'\fR parameter. It also takes the usual \f(CW\*(C`flags\*(C'\fR
+parameter.  The final parameter, \f(CW\*(C`argv\*(C'\fR, consists of a NULL-terminated
+list of C strings to be passed as parameters to the Perl subroutine.
+See "Using call_argv".
+.PP
+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.
+.PP
+As a general rule you should \fIalways\fR 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.
+.SH "FLAG VALUES"
+.IX Header "FLAG VALUES"
+The \f(CW\*(C`flags\*(C'\fR parameter in all the \fIcall_*\fR functions is one of \f(CW\*(C`G_VOID\*(C'\fR,
+\&\f(CW\*(C`G_SCALAR\*(C'\fR, or \f(CW\*(C`G_LIST\*(C'\fR, which indicate the call context, OR'ed together
+with a bit mask of any combination of the other G_* symbols defined below.
+.SS G_VOID
+.IX Subsection "G_VOID"
+Calls the Perl subroutine in a void context.
+.PP
+This flag has 2 effects:
+.IP 1. 5
+It indicates to the subroutine being called that it is executing in
+a void context (if it executes \fIwantarray\fR the result will be the
+undefined value).
+.IP 2. 5
+It ensures that nothing is actually returned from the subroutine.
+.PP
+The value returned by the \fIcall_*\fR function indicates how many
+items have been returned by the Perl subroutine\-\-in this case it will
+be 0.
+.SS G_SCALAR
+.IX Subsection "G_SCALAR"
+Calls the Perl subroutine in a scalar context.  This is the default
+context flag setting for all the \fIcall_*\fR functions.
+.PP
+This flag has 2 effects:
+.IP 1. 5
+It indicates to the subroutine being called that it is executing in a
+scalar context (if it executes \fIwantarray\fR the result will be false).
+.IP 2. 5
+It ensures that only a scalar is actually returned from the subroutine.
+The subroutine can, of course,  ignore the \fIwantarray\fR and return a
+list anyway. If so, then only the last element of the list will be
+returned.
+.PP
+The value returned by the \fIcall_*\fR function indicates how many
+items have been returned by the Perl subroutine \- in this case it will
+be either 0 or 1.
+.PP
+If 0, then you have specified the G_DISCARD flag.
+.PP
+If 1, then the item actually returned by the Perl subroutine will be
+stored on the Perl stack \- the section "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
+\&\fIcall_*\fR function.  The section "Returning a List in Scalar
+Context" shows an example of this behavior.
+.SS G_LIST
+.IX Subsection "G_LIST"
+Calls the Perl subroutine in a list context. Prior to Perl version
+5.35.1 this was called \f(CW\*(C`G_ARRAY\*(C'\fR.
+.PP
+As with G_SCALAR, this flag has 2 effects:
+.IP 1. 5
+It indicates to the subroutine being called that it is executing in a
+list context (if it executes \fIwantarray\fR the result will be true).
+.IP 2. 5
+It ensures that all items returned from the subroutine will be
+accessible when control returns from the \fIcall_*\fR function.
+.PP
+The value returned by the \fIcall_*\fR function indicates how many
+items have been returned by the Perl subroutine.
+.PP
+If 0, then you have specified the G_DISCARD flag.
+.PP
+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 "Returning a List of Values" gives an example of using the
+G_LIST flag and the mechanics of accessing the returned items from the
+Perl stack.
+.SS G_DISCARD
+.IX Subsection "G_DISCARD"
+By default, the \fIcall_*\fR 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_LIST.
+.PP
+If you do not set this flag then it is \fIvery\fR 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 "Returning a Scalar" gives details of how to
+dispose of these temporaries explicitly and the section "Using Perl to
+Dispose of Temporaries" discusses the specific circumstances where you
+can ignore the problem and let Perl deal with it for you.
+.SS G_NOARGS
+.IX Subsection "G_NOARGS"
+Whenever a Perl subroutine is called using one of the \fIcall_*\fR
+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 \f(CW@_\fR array for the Perl subroutine.
+.PP
+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.
+.PP
+In fact, what can happen is that the Perl subroutine you have called
+can access the \f(CW@_\fR array from a previous Perl subroutine.  This will
+occur when the code that is executing the \fIcall_*\fR function has
+itself been called from another Perl subroutine. The code below
+illustrates this
+.PP
+.Vb 2
+\&    sub fred
+\&      { print "@_\en"  }
+\&
+\&    sub joe
+\&      { &fred }
+\&
+\&    &joe(1,2,3);
+.Ve
+.PP
+This will print
+.PP
+.Vb 1
+\&    1 2 3
+.Ve
+.PP
+What has happened is that \f(CW\*(C`fred\*(C'\fR accesses the \f(CW@_\fR array which
+belongs to \f(CW\*(C`joe\*(C'\fR.
+.SS G_EVAL
+.IX Subsection "G_EVAL"
+It is possible for the Perl subroutine you are calling to terminate
+abnormally, e.g., by calling \fIdie\fR explicitly or by not actually
+existing.  By default, when either of these events occurs, the
+process will terminate immediately.  If you want to trap this
+type of event, specify the G_EVAL flag.  It will put an \fIeval { }\fR
+around the subroutine call.
+.PP
+Whenever control returns from the \fIcall_*\fR function you need to
+check the \f(CW$@\fR variable as you would in a normal Perl script.
+.PP
+The value returned from the \fIcall_*\fR 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:
+.IP \(bu 5
+If the \fIcall_*\fR function returns normally, then the value
+returned is as specified in the previous sections.
+.IP \(bu 5
+If G_DISCARD is specified, the return value will always be 0.
+.IP \(bu 5
+If G_LIST is specified \fIand\fR an error has occurred, the return value
+will always be 0.
+.IP \(bu 5
+If G_SCALAR is specified \fIand\fR an error has occurred, the return value
+will be 1 and the value on the top of the stack will be \fIundef\fR. This
+means that if you have already detected the error by checking \f(CW$@\fR and
+you want the program to continue, you must remember to pop the \fIundef\fR
+from the stack.
+.PP
+See "Using G_EVAL" for details on using G_EVAL.
+.SS G_KEEPERR
+.IX Subsection "G_KEEPERR"
+Using the G_EVAL flag described above will always set \f(CW$@\fR: clearing
+it if there was no error, and setting it to describe the error if there
+was an error in the called code.  This is what you want if your intention
+is to handle possible errors, but sometimes you just want to trap errors
+and stop them interfering with the rest of the program.
+.PP
+This scenario will mostly be applicable to code that is meant to be called
+from within destructors, asynchronous callbacks, and signal handlers.
+In such situations, where the code being called has little relation to the
+surrounding dynamic context, the main program needs to be insulated from
+errors in the called code, even if they can't be handled intelligently.
+It may also be useful to do this with code for \f(CW\*(C`_\|_DIE_\|_\*(C'\fR or \f(CW\*(C`_\|_WARN_\|_\*(C'\fR
+hooks, and \f(CW\*(C`tie\*(C'\fR functions.
+.PP
+The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
+\&\fIcall_*\fR functions that are used to implement such code, or with
+\&\f(CW\*(C`eval_sv\*(C'\fR.  This flag has no effect on the \f(CW\*(C`call_*\*(C'\fR functions when
+G_EVAL is not used.
+.PP
+When G_KEEPERR is used, any error in the called code will terminate the
+call as usual, and the error will not propagate beyond the call (as usual
+for G_EVAL), but it will not go into \f(CW$@\fR.  Instead the error will be
+converted into a warning, prefixed with the string "\et(in cleanup)".
+This can be disabled using \f(CW\*(C`no warnings \*(Aqmisc\*(Aq\*(C'\fR.  If there is no error,
+\&\f(CW$@\fR will not be cleared.
+.PP
+Note that the G_KEEPERR flag does not propagate into inner evals; these
+may still set \f(CW$@\fR.
+.PP
+The G_KEEPERR flag was introduced in Perl version 5.002.
+.PP
+See "Using G_KEEPERR" for an example of a situation that warrants the
+use of this flag.
+.SS "Determining the Context"
+.IX Subsection "Determining the Context"
+As mentioned above, you can determine the context of the currently
+executing subroutine in Perl with \fIwantarray\fR.  The equivalent test
+can be made in C by using the \f(CW\*(C`GIMME_V\*(C'\fR macro, which returns
+\&\f(CW\*(C`G_LIST\*(C'\fR if you have been called in a list context, \f(CW\*(C`G_SCALAR\*(C'\fR if
+in a scalar context, or \f(CW\*(C`G_VOID\*(C'\fR if in a void context (i.e., the
+return value will not be used).  An older version of this macro is
+called \f(CW\*(C`GIMME\*(C'\fR; in a void context it returns \f(CW\*(C`G_SCALAR\*(C'\fR instead of
+\&\f(CW\*(C`G_VOID\*(C'\fR.  An example of using the \f(CW\*(C`GIMME_V\*(C'\fR macro is shown in
+section "Using GIMME_V".
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+Enough of the definition talk! Let's have a few examples.
+.PP
+Perl provides many macros to assist in accessing the Perl stack.
+Wherever possible, these macros should always be used when interfacing
+to Perl internals.  We hope this should make the code less vulnerable
+to any changes made to Perl in the future.
+.PP
+Another point worth noting is that in the first series of examples I
+have made use of only the \fIcall_pv\fR function.  This has been done
+to keep the code simpler and ease you into the topic.  Wherever
+possible, if the choice is between using \fIcall_pv\fR and
+\&\fIcall_sv\fR, you should always try to use \fIcall_sv\fR.  See
+"Using call_sv" for details.
+.SS "No Parameters, Nothing Returned"
+.IX Subsection "No Parameters, Nothing Returned"
+This first trivial example will call a Perl subroutine, \fIPrintUID\fR, to
+print out the UID of the process.
+.PP
+.Vb 4
+\&    sub PrintUID
+\&    {
+\&        print "UID is $<\en";
+\&    }
+.Ve
+.PP
+and here is a C function to call it
+.PP
+.Vb 4
+\&    static void
+\&    call_PrintUID()
+\&    {
+\&        dSP;
+\&
+\&        PUSHMARK(SP);
+\&        call_pv("PrintUID", G_DISCARD|G_NOARGS);
+\&    }
+.Ve
+.PP
+Simple, eh?
+.PP
+A few points to note about this example:
+.IP 1. 5
+Ignore \f(CW\*(C`dSP\*(C'\fR and \f(CWPUSHMARK(SP)\fR for now. They will be discussed in
+the next example.
+.IP 2. 5
+We aren't passing any parameters to \fIPrintUID\fR so G_NOARGS can be
+specified.
+.IP 3. 5
+We aren't interested in anything returned from \fIPrintUID\fR, so
+G_DISCARD is specified. Even if \fIPrintUID\fR was changed to
+return some value(s), having specified G_DISCARD will mean that they
+will be wiped by the time control returns from \fIcall_pv\fR.
+.IP 4. 5
+As \fIcall_pv\fR 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.
+.IP 5. 5
+Because we specified G_DISCARD, it is not necessary to check the value
+returned from \fIcall_pv\fR. It will always be 0.
+.SS "Passing Parameters"
+.IX Subsection "Passing Parameters"
+Now let's make a slightly more complex example. This time we want to
+call a Perl subroutine, \f(CW\*(C`LeftString\*(C'\fR, which will take 2 parameters\-\-a
+string ($s) and an integer ($n).  The subroutine will simply
+print the first \f(CW$n\fR characters of the string.
+.PP
+So the Perl subroutine would look like this:
+.PP
+.Vb 5
+\&    sub LeftString
+\&    {
+\&        my($s, $n) = @_;
+\&        print substr($s, 0, $n), "\en";
+\&    }
+.Ve
+.PP
+The C function required to call \fILeftString\fR would look like this:
+.PP
+.Vb 6
+\&    static void
+\&    call_LeftString(a, b)
+\&    char * a;
+\&    int b;
+\&    {
+\&        dSP;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSVpv(a, 0)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        call_pv("LeftString", G_DISCARD);
+\&
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+Here are a few notes on the C function \fIcall_LeftString\fR.
+.IP 1. 5
+Parameters are passed to the Perl subroutine using the Perl stack.
+This is the purpose of the code beginning with the line \f(CW\*(C`dSP\*(C'\fR and
+ending with the line \f(CW\*(C`PUTBACK\*(C'\fR.  The \f(CW\*(C`dSP\*(C'\fR declares a local copy
+of the stack pointer.  This local copy should \fBalways\fR be accessed
+as \f(CW\*(C`SP\*(C'\fR.
+.IP 2. 5
+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 \f(CW\*(C`dSP\*(C'\fR\-\-it declares
+and initializes a \fIlocal\fR copy of the Perl stack pointer.
+.Sp
+All the other macros which will be used in this example require you to
+have used this macro.
+.Sp
+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
+use the \f(CW\*(C`dSP\*(C'\fR macro explicitly\-\-it will be declared for you
+automatically.
+.IP 3. 5
+Any parameters to be pushed onto the stack should be bracketed by the
+\&\f(CW\*(C`PUSHMARK\*(C'\fR and \f(CW\*(C`PUTBACK\*(C'\fR macros.  The purpose of these two macros, in
+this context, is to count the number of parameters you are
+pushing automatically.  Then whenever Perl is creating the \f(CW@_\fR array for the
+subroutine, it knows how big to make it.
+.Sp
+The \f(CW\*(C`PUSHMARK\*(C'\fR 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 "No Parameters, Nothing Returned") you
+must still call the \f(CW\*(C`PUSHMARK\*(C'\fR macro before you can call any of the
+\&\fIcall_*\fR functions\-\-Perl still needs to know that there are no
+parameters.
+.Sp
+The \f(CW\*(C`PUTBACK\*(C'\fR macro sets the global copy of the stack pointer to be
+the same as our local copy. If we didn't do this, \fIcall_pv\fR
+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, \fInot\fR the global copy.
+.IP 4. 5
+Next, we come to EXTEND and PUSHs. This is where the parameters
+actually get pushed onto the stack. In this case we are pushing a
+string and an integer.
+.Sp
+Alternatively you can use the \fBXPUSHs()\fR macro, which combines a
+\&\f(CW\*(C`EXTEND(SP, 1)\*(C'\fR and \f(CWPUSHs()\fR.  This is less efficient if you're
+pushing multiple values.
+.Sp
+See "XSUBs and the Argument Stack" in perlguts for details
+on how the PUSH macros work.
+.IP 5. 5
+Because we created temporary values (by means of \fBsv_2mortal()\fR calls)
+we will have to tidy up the Perl stack and dispose of mortal SVs.
+.Sp
+This is the purpose of
+.Sp
+.Vb 2
+\&    ENTER;
+\&    SAVETMPS;
+.Ve
+.Sp
+at the start of the function, and
+.Sp
+.Vb 2
+\&    FREETMPS;
+\&    LEAVE;
+.Ve
+.Sp
+at the end. The \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR 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.
+.Sp
+The \f(CW\*(C`FREETMPS\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pair will get rid of any values returned by
+the Perl subroutine (see next example), plus it will also dump the
+mortal SVs we have created.  Having \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR at the
+beginning of the code makes sure that no other mortals are destroyed.
+.Sp
+Think of these macros as working a bit like \f(CW\*(C`{\*(C'\fR and \f(CW\*(C`}\*(C'\fR in Perl
+to limit the scope of local variables.
+.Sp
+See the section "Using Perl to Dispose of Temporaries" for details of
+an alternative to using these macros.
+.IP 6. 5
+Finally, \fILeftString\fR can now be called via the \fIcall_pv\fR function.
+The only flag specified this time is G_DISCARD. Because we are passing
+2 parameters to the Perl subroutine this time, we have not specified
+G_NOARGS.
+.SS "Returning a Scalar"
+.IX Subsection "Returning a Scalar"
+Now for an example of dealing with the items returned from a Perl
+subroutine.
+.PP
+Here is a Perl subroutine, \fIAdder\fR, that takes 2 integer parameters
+and simply returns their sum.
+.PP
+.Vb 5
+\&    sub Adder
+\&    {
+\&        my($a, $b) = @_;
+\&        $a + $b;
+\&    }
+.Ve
+.PP
+Because we are now concerned with the return value from \fIAdder\fR, the C
+function required to call it is now a bit more complex.
+.PP
+.Vb 7
+\&    static void
+\&    call_Adder(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("Adder", G_SCALAR);
+\&
+\&        SPAGAIN;
+\&
+\&        if (count != 1)
+\&            croak("Big trouble\en");
+\&
+\&        printf ("The sum of %d and %d is %d\en", a, b, POPi);
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+Points to note this time are
+.IP 1. 5
+The only flag specified this time was G_SCALAR. That means that the \f(CW@_\fR
+array will be created and that the value returned by \fIAdder\fR will
+still exist after the call to \fIcall_pv\fR.
+.IP 2. 5
+The purpose of the macro \f(CW\*(C`SPAGAIN\*(C'\fR 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 reallocated during the
+\&\fIcall_pv\fR call.
+.Sp
+If you are making use of the Perl stack pointer in your code you must
+always refresh the local copy using SPAGAIN whenever you make use
+of the \fIcall_*\fR functions or any other Perl internal function.
+.IP 3. 5
+Although only a single value was expected to be returned from \fIAdder\fR,
+it is still good practice to check the return code from \fIcall_pv\fR
+anyway.
+.Sp
+Expecting a single value is not quite the same as knowing that there
+will be one. If someone modified \fIAdder\fR 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
+\&\fIreally\fR don't want to happen ever.
+.IP 4. 5
+The \f(CW\*(C`POPi\*(C'\fR macro is used here to pop the return value from the stack.
+In this case we wanted an integer, so \f(CW\*(C`POPi\*(C'\fR was used.
+.Sp
+Here is the complete list of POP macros available, along with the types
+they return.
+.Sp
+.Vb 8
+\&    POPs        SV
+\&    POPp        pointer (PV)
+\&    POPpbytex   pointer to bytes (PV)
+\&    POPn        double (NV)
+\&    POPi        integer (IV)
+\&    POPu        unsigned integer (UV)
+\&    POPl        long
+\&    POPul       unsigned long
+.Ve
+.Sp
+Since these macros have side-effects don't use them as arguments to
+macros that may evaluate their argument several times, for example:
+.Sp
+.Vb 3
+\&  /* Bad idea, don\*(Aqt do this */
+\&  STRLEN len;
+\&  const char *s = SvPV(POPs, len);
+.Ve
+.Sp
+Instead, use a temporary:
+.Sp
+.Vb 3
+\&  STRLEN len;
+\&  SV *sv = POPs;
+\&  const char *s = SvPV(sv, len);
+.Ve
+.Sp
+or a macro that guarantees it will evaluate its arguments only once:
+.Sp
+.Vb 2
+\&  STRLEN len;
+\&  const char *s = SvPVx(POPs, len);
+.Ve
+.IP 5. 5
+The final \f(CW\*(C`PUTBACK\*(C'\fR 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 \f(CW\*(C`POPi\*(C'\fR it updated only our
+local copy of the stack pointer.  Remember, \f(CW\*(C`PUTBACK\*(C'\fR sets the global
+stack pointer to be the same as our local copy.
+.SS "Returning a List of Values"
+.IX Subsection "Returning a List of Values"
+Now, let's extend the previous example to return both the sum of the
+parameters and the difference.
+.PP
+Here is the Perl subroutine
+.PP
+.Vb 5
+\&    sub AddSubtract
+\&    {
+\&       my($a, $b) = @_;
+\&       ($a+$b, $a\-$b);
+\&    }
+.Ve
+.PP
+and this is the C function
+.PP
+.Vb 7
+\&    static void
+\&    call_AddSubtract(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("AddSubtract", G_LIST);
+\&
+\&        SPAGAIN;
+\&
+\&        if (count != 2)
+\&            croak("Big trouble\en");
+\&
+\&        printf ("%d \- %d = %d\en", a, b, POPi);
+\&        printf ("%d + %d = %d\en", a, b, POPi);
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+If \fIcall_AddSubtract\fR is called like this
+.PP
+.Vb 1
+\&    call_AddSubtract(7, 4);
+.Ve
+.PP
+then here is the output
+.PP
+.Vb 2
+\&    7 \- 4 = 3
+\&    7 + 4 = 11
+.Ve
+.PP
+Notes
+.IP 1. 5
+We wanted list context, so G_LIST was used.
+.IP 2. 5
+Not surprisingly \f(CW\*(C`POPi\*(C'\fR is used twice this time because we were
+retrieving 2 values from the stack. The important thing to note is that
+when using the \f(CW\*(C`POP*\*(C'\fR macros they come off the stack in \fIreverse\fR
+order.
+.SS "Returning a List in Scalar Context"
+.IX Subsection "Returning a List in Scalar Context"
+Say the Perl subroutine in the previous section was called in a scalar
+context, like this
+.PP
+.Vb 8
+\&    static void
+\&    call_AddSubScalar(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&        int i;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("AddSubtract", G_SCALAR);
+\&
+\&        SPAGAIN;
+\&
+\&        printf ("Items Returned = %d\en", count);
+\&
+\&        for (i = 1; i <= count; ++i)
+\&            printf ("Value %d = %d\en", i, POPi);
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+The other modification made is that \fIcall_AddSubScalar\fR will print the
+number of items returned from the Perl subroutine and their value (for
+simplicity it assumes that they are integer).  So if
+\&\fIcall_AddSubScalar\fR is called
+.PP
+.Vb 1
+\&    call_AddSubScalar(7, 4);
+.Ve
+.PP
+then the output will be
+.PP
+.Vb 2
+\&    Items Returned = 1
+\&    Value 1 = 3
+.Ve
+.PP
+In this case the main point to note is that only the last item in the
+list is returned from the subroutine. \fIAddSubtract\fR actually made it back to
+\&\fIcall_AddSubScalar\fR.
+.SS "Returning Data from Perl via the Parameter List"
+.IX Subsection "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.
+.PP
+The Perl subroutine, \fIInc\fR, below takes 2 parameters and increments
+each directly.
+.PP
+.Vb 5
+\&    sub Inc
+\&    {
+\&        ++ $_[0];
+\&        ++ $_[1];
+\&    }
+.Ve
+.PP
+and here is a C function to call it.
+.PP
+.Vb 9
+\&    static void
+\&    call_Inc(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        int count;
+\&        SV * sva;
+\&        SV * svb;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        sva = sv_2mortal(newSViv(a));
+\&        svb = sv_2mortal(newSViv(b));
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sva);
+\&        PUSHs(svb);
+\&        PUTBACK;
+\&
+\&        count = call_pv("Inc", G_DISCARD);
+\&
+\&        if (count != 0)
+\&            croak ("call_Inc: expected 0 values from \*(AqInc\*(Aq, got %d\en",
+\&                   count);
+\&
+\&        printf ("%d + 1 = %d\en", a, SvIV(sva));
+\&        printf ("%d + 1 = %d\en", b, SvIV(svb));
+\&
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+To be able to access the two parameters that were pushed onto the stack
+after they return from \fIcall_pv\fR it is necessary to make a note
+of their addresses\-\-thus the two variables \f(CW\*(C`sva\*(C'\fR and \f(CW\*(C`svb\*(C'\fR.
+.PP
+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 \fIcall_pv\fR.
+.SS "Using G_EVAL"
+.IX Subsection "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 \fIdie\fR.
+.PP
+.Vb 3
+\&    sub Subtract
+\&    {
+\&        my ($a, $b) = @_;
+\&
+\&        die "death can be fatal\en" if $a < $b;
+\&
+\&        $a \- $b;
+\&    }
+.Ve
+.PP
+and some C to call it
+.PP
+.Vb 8
+\& static void
+\& call_Subtract(a, b)
+\& int a;
+\& int b;
+\& {
+\&     dSP;
+\&     int count;
+\&     SV *err_tmp;
+\&
+\&     ENTER;
+\&     SAVETMPS;
+\&
+\&     PUSHMARK(SP);
+\&     EXTEND(SP, 2);
+\&     PUSHs(sv_2mortal(newSViv(a)));
+\&     PUSHs(sv_2mortal(newSViv(b)));
+\&     PUTBACK;
+\&
+\&     count = call_pv("Subtract", G_EVAL|G_SCALAR);
+\&
+\&     SPAGAIN;
+\&
+\&     /* Check the eval first */
+\&     err_tmp = ERRSV;
+\&     if (SvTRUE(err_tmp))
+\&     {
+\&         printf ("Uh oh \- %s\en", SvPV_nolen(err_tmp));
+\&         POPs;
+\&     }
+\&     else
+\&     {
+\&       if (count != 1)
+\&        croak("call_Subtract: wanted 1 value from \*(AqSubtract\*(Aq, got %d\en",
+\&              count);
+\&
+\&         printf ("%d \- %d = %d\en", a, b, POPi);
+\&     }
+\&
+\&     PUTBACK;
+\&     FREETMPS;
+\&     LEAVE;
+\& }
+.Ve
+.PP
+If \fIcall_Subtract\fR is called thus
+.PP
+.Vb 1
+\&    call_Subtract(4, 5)
+.Ve
+.PP
+the following will be printed
+.PP
+.Vb 1
+\&    Uh oh \- death can be fatal
+.Ve
+.PP
+Notes
+.IP 1. 5
+We want to be able to catch the \fIdie\fR so we have used the G_EVAL
+flag.  Not specifying this flag would mean that the program would
+terminate immediately at the \fIdie\fR statement in the subroutine
+\&\fISubtract\fR.
+.IP 2. 5
+The code
+.Sp
+.Vb 6
+\&    err_tmp = ERRSV;
+\&    if (SvTRUE(err_tmp))
+\&    {
+\&        printf ("Uh oh \- %s\en", SvPV_nolen(err_tmp));
+\&        POPs;
+\&    }
+.Ve
+.Sp
+is the direct equivalent of this bit of Perl
+.Sp
+.Vb 1
+\&    print "Uh oh \- $@\en" if $@;
+.Ve
+.Sp
+\&\f(CW\*(C`PL_errgv\*(C'\fR is a perl global of type \f(CW\*(C`GV *\*(C'\fR that points to the symbol
+table entry containing the error.  \f(CW\*(C`ERRSV\*(C'\fR therefore refers to the C
+equivalent of \f(CW$@\fR.  We use a local temporary, \f(CW\*(C`err_tmp\*(C'\fR, since
+\&\f(CW\*(C`ERRSV\*(C'\fR is a macro that calls a function, and \f(CWSvTRUE(ERRSV)\fR would
+end up calling that function multiple times.
+.IP 3. 5
+Note that the stack is popped using \f(CW\*(C`POPs\*(C'\fR in the block where
+\&\f(CWSvTRUE(err_tmp)\fR is true.  This is necessary because whenever a
+\&\fIcall_*\fR function invoked with G_EVAL|G_SCALAR returns an error,
+the top of the stack holds the value \fIundef\fR. Because we want the
+program to continue after detecting this error, it is essential that
+the stack be tidied up by removing the \fIundef\fR.
+.SS "Using G_KEEPERR"
+.IX Subsection "Using G_KEEPERR"
+Consider this rather facetious example, where we have used an XS
+version of the call_Subtract example above inside a destructor:
+.PP
+.Vb 9
+\&    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\*(Aqt
+.Ve
+.PP
+This example will fail to recognize that an error occurred inside the
+\&\f(CW\*(C`eval {}\*(C'\fR.  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 \fIcall_pv\fR using the G_EVAL
+flag, it promptly reset \f(CW$@\fR.  This results in the failure of the
+outermost test for \f(CW$@\fR, and thereby the failure of the error trap.
+.PP
+Appending the G_KEEPERR flag, so that the \fIcall_pv\fR call in
+call_Subtract reads:
+.PP
+.Vb 1
+\&        count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
+.Ve
+.PP
+will preserve the error and restore reliable error handling.
+.SS "Using call_sv"
+.IX Subsection "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, and you'll want to use
+call_sv.
+.PP
+Consider the Perl code below
+.PP
+.Vb 4
+\&    sub fred
+\&    {
+\&        print "Hello there\en";
+\&    }
+\&
+\&    CallSubPV("fred");
+.Ve
+.PP
+Here is a snippet of XSUB which defines \fICallSubPV\fR.
+.PP
+.Vb 6
+\&    void
+\&    CallSubPV(name)
+\&        char *  name
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_pv(name, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+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 \fIcall_sv\fR is useful.
+.PP
+The code below for \fICallSubSV\fR is identical to \fICallSubPV\fR except
+that the \f(CW\*(C`name\*(C'\fR parameter is now defined as an SV* and we use
+\&\fIcall_sv\fR instead of \fIcall_pv\fR.
+.PP
+.Vb 6
+\&    void
+\&    CallSubSV(name)
+\&        SV *    name
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_sv(name, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+Because we are using an SV to call \fIfred\fR the following can all be used:
+.PP
+.Vb 5
+\&    CallSubSV("fred");
+\&    CallSubSV(\e&fred);
+\&    $ref = \e&fred;
+\&    CallSubSV($ref);
+\&    CallSubSV( sub { print "Hello there\en" } );
+.Ve
+.PP
+As you can see, \fIcall_sv\fR gives you much greater flexibility in
+how you can specify the Perl subroutine.
+.PP
+You should note that, if it is necessary to store the SV (\f(CW\*(C`name\*(C'\fR 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:
+.PP
+.Vb 1
+\&    static SV * rememberSub;
+\&
+\&    void
+\&    SaveSub1(name)
+\&        SV *    name
+\&        CODE:
+\&        rememberSub = name;
+\&
+\&    void
+\&    CallSavedSub1()
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        call_sv(rememberSub, G_DISCARD|G_NOARGS);
+.Ve
+.PP
+The reason this is wrong is that, by the time you come to use the
+pointer \f(CW\*(C`rememberSub\*(C'\fR in \f(CW\*(C`CallSavedSub1\*(C'\fR, it may or may not still refer
+to the Perl subroutine that was recorded in \f(CW\*(C`SaveSub1\*(C'\fR.  This is
+particularly true for these cases:
+.PP
+.Vb 2
+\&    SaveSub1(\e&fred);
+\&    CallSavedSub1();
+\&
+\&    SaveSub1( sub { print "Hello there\en" } );
+\&    CallSavedSub1();
+.Ve
+.PP
+By the time each of the \f(CW\*(C`SaveSub1\*(C'\fR 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
+.PP
+.Vb 1
+\&    Can\*(Aqt use an undefined value as a subroutine reference at ...
+.Ve
+.PP
+for each of the \f(CW\*(C`CallSavedSub1\*(C'\fR lines.
+.PP
+Similarly, with this code
+.PP
+.Vb 4
+\&    $ref = \e&fred;
+\&    SaveSub1($ref);
+\&    $ref = 47;
+\&    CallSavedSub1();
+.Ve
+.PP
+you can expect one of these messages (which you actually get is dependent on
+the version of Perl you are using)
+.PP
+.Vb 2
+\&    Not a CODE reference at ...
+\&    Undefined subroutine &main::47 called ...
+.Ve
+.PP
+The variable \f(CW$ref\fR may have referred to the subroutine \f(CW\*(C`fred\*(C'\fR
+whenever the call to \f(CW\*(C`SaveSub1\*(C'\fR was made but by the time
+\&\f(CW\*(C`CallSavedSub1\*(C'\fR gets called it now holds the number \f(CW47\fR. Because we
+saved only a pointer to the original SV in \f(CW\*(C`SaveSub1\*(C'\fR, any changes to
+\&\f(CW$ref\fR will be tracked by the pointer \f(CW\*(C`rememberSub\*(C'\fR. This means that
+whenever \f(CW\*(C`CallSavedSub1\*(C'\fR gets called, it will attempt to execute the
+code which is referenced by the SV* \f(CW\*(C`rememberSub\*(C'\fR.  In this case
+though, it now refers to the integer \f(CW47\fR, so expect Perl to complain
+loudly.
+.PP
+A similar but more subtle problem is illustrated with this code:
+.PP
+.Vb 4
+\&    $ref = \e&fred;
+\&    SaveSub1($ref);
+\&    $ref = \e&joe;
+\&    CallSavedSub1();
+.Ve
+.PP
+This time whenever \f(CW\*(C`CallSavedSub1\*(C'\fR gets called it will execute the Perl
+subroutine \f(CW\*(C`joe\*(C'\fR (assuming it exists) rather than \f(CW\*(C`fred\*(C'\fR as was
+originally requested in the call to \f(CW\*(C`SaveSub1\*(C'\fR.
+.PP
+To get around these problems it is necessary to take a full copy of the
+SV.  The code below shows \f(CW\*(C`SaveSub2\*(C'\fR modified to do that.
+.PP
+.Vb 2
+\&    /* this isn\*(Aqt thread\-safe */
+\&    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);
+.Ve
+.PP
+To avoid creating a new SV every time \f(CW\*(C`SaveSub2\*(C'\fR 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 \f(CW\*(C`name\*(C'\fR is copied to the variable \f(CW\*(C`keepSub\*(C'\fR in one
+operation using \f(CW\*(C`newSVsv\*(C'\fR.  Thereafter, whenever \f(CW\*(C`SaveSub2\*(C'\fR is called,
+the existing SV, \f(CW\*(C`keepSub\*(C'\fR, is overwritten with the new value using
+\&\f(CW\*(C`SvSetSV\*(C'\fR.
+.PP
+Note: using a static or global variable to store the SV isn't
+thread-safe.  You can either use the \f(CW\*(C`MY_CXT\*(C'\fR mechanism documented in
+"Safely Storing Static Data in XS" in perlxs which is fast, or store the
+values in perl global variables, using \fBget_sv()\fR, which is much slower.
+.SS "Using call_argv"
+.IX Subsection "Using call_argv"
+Here is a Perl subroutine which prints whatever parameters are passed
+to it.
+.PP
+.Vb 3
+\&    sub PrintList
+\&    {
+\&        my(@list) = @_;
+\&
+\&        foreach (@list) { print "$_\en" }
+\&    }
+.Ve
+.PP
+And here is an example of \fIcall_argv\fR which will call
+\&\fIPrintList\fR.
+.PP
+.Vb 1
+\&    static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
+\&
+\&    static void
+\&    call_PrintList()
+\&    {
+\&        call_argv("PrintList", G_DISCARD, words);
+\&    }
+.Ve
+.PP
+Note that it is not necessary to call \f(CW\*(C`PUSHMARK\*(C'\fR in this instance.
+This is because \fIcall_argv\fR will do it for you.
+.SS "Using call_method"
+.IX Subsection "Using call_method"
+Consider the following Perl code:
+.PP
+.Vb 2
+\&    {
+\&        package Mine;
+\&
+\&        sub new
+\&        {
+\&            my($type) = shift;
+\&            bless [@_]
+\&        }
+\&
+\&        sub Display
+\&        {
+\&            my ($self, $index) = @_;
+\&            print "$index: $$self[$index]\en";
+\&        }
+\&
+\&        sub PrintID
+\&        {
+\&            my($class) = @_;
+\&            print "This is Class $class version 1.0\en";
+\&        }
+\&    }
+.Ve
+.PP
+It implements just a very simple class to manage an array.  Apart from
+the constructor, \f(CW\*(C`new\*(C'\fR, it declares methods, one static and one
+virtual. The static method, \f(CW\*(C`PrintID\*(C'\fR, prints out simply the class
+name and a version number. The virtual method, \f(CW\*(C`Display\*(C'\fR, prints out a
+single element of the array.  Here is an all-Perl example of using it.
+.PP
+.Vb 3
+\&    $a = Mine\->new(\*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq);
+\&    $a\->Display(1);
+\&    Mine\->PrintID;
+.Ve
+.PP
+will print
+.PP
+.Vb 2
+\&    1: green
+\&    This is Class Mine version 1.0
+.Ve
+.PP
+Calling a Perl method from C is fairly straightforward. The following
+things are required:
+.IP \(bu 5
+A reference to the object for a virtual method or the name of the class
+for a static method
+.IP \(bu 5
+The name of the method
+.IP \(bu 5
+Any other parameters specific to the method
+.PP
+Here is a simple XSUB which illustrates the mechanics of calling both
+the \f(CW\*(C`PrintID\*(C'\fR and \f(CW\*(C`Display\*(C'\fR methods from C.
+.PP
+.Vb 11
+\&    void
+\&    call_Method(ref, method, index)
+\&        SV *    ref
+\&        char *  method
+\&        int             index
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(ref);
+\&        PUSHs(sv_2mortal(newSViv(index)));
+\&        PUTBACK;
+\&
+\&        call_method(method, G_DISCARD);
+\&
+\&    void
+\&    call_PrintID(class, method)
+\&        char *  class
+\&        char *  method
+\&        CODE:
+\&        PUSHMARK(SP);
+\&        XPUSHs(sv_2mortal(newSVpv(class, 0)));
+\&        PUTBACK;
+\&
+\&        call_method(method, G_DISCARD);
+.Ve
+.PP
+So the methods \f(CW\*(C`PrintID\*(C'\fR and \f(CW\*(C`Display\*(C'\fR can be invoked like this:
+.PP
+.Vb 3
+\&    $a = Mine\->new(\*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq);
+\&    call_Method($a, \*(AqDisplay\*(Aq, 1);
+\&    call_PrintID(\*(AqMine\*(Aq, \*(AqPrintID\*(Aq);
+.Ve
+.PP
+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 \fIcall_method\fR.
+.SS "Using GIMME_V"
+.IX Subsection "Using GIMME_V"
+Here is a trivial XSUB which prints the context in which it is
+currently executing.
+.PP
+.Vb 10
+\&    void
+\&    PrintContext()
+\&        CODE:
+\&        U8 gimme = GIMME_V;
+\&        if (gimme == G_VOID)
+\&            printf ("Context is Void\en");
+\&        else if (gimme == G_SCALAR)
+\&            printf ("Context is Scalar\en");
+\&        else
+\&            printf ("Context is Array\en");
+.Ve
+.PP
+And here is some Perl to test it.
+.PP
+.Vb 3
+\&    PrintContext;
+\&    $a = PrintContext;
+\&    @a = PrintContext;
+.Ve
+.PP
+The output from that will be
+.PP
+.Vb 3
+\&    Context is Void
+\&    Context is Scalar
+\&    Context is Array
+.Ve
+.SS "Using Perl to Dispose of Temporaries"
+.IX Subsection "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 \fIcall_*\fR function or
+values returned via the stack) have been freed by one of these methods:
+.IP \(bu 5
+Specifying the G_DISCARD flag with \fIcall_*\fR
+.IP \(bu 5
+Explicitly using the \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`SAVETMPS\*(C'\fR\-\-\f(CW\*(C`FREETMPS\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR pairing
+.PP
+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
+.PP
+.Vb 5
+\&    ENTER;
+\&    SAVETMPS;
+\&    ...
+\&    FREETMPS;
+\&    LEAVE;
+.Ve
+.PP
+sequence in the callback (and not, of course, specifying the G_DISCARD
+flag).
+.PP
+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.
+.PP
+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.
+.PP
+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
+.PP
+.Vb 1
+\&    perl \-\-> XSUB \-\-> external library
+.Ve
+.PP
+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
+.PP
+.Vb 7
+\&    perl \-\-> XSUB \-\-> external library
+\&                      ...
+\&                      error occurs
+\&                      ...
+\&                      external library \-\-> call_* \-\-> perl
+\&                                                          |
+\&    perl <\-\- XSUB <\-\- external library <\-\- call_* <\-\-\-\-+
+.Ve
+.PP
+After processing of the error using \fIcall_*\fR is completed,
+control reverts back to Perl more or less immediately.
+.PP
+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.
+.PP
+In the second example, an event driven program, the flow of control
+will be more like this
+.PP
+.Vb 10
+\&    perl \-\-> XSUB \-\-> event handler
+\&                      ...
+\&                      event handler \-\-> call_* \-\-> perl
+\&                                                       |
+\&                      event handler <\-\- call_* <\-\-\-\-+
+\&                      ...
+\&                      event handler \-\-> call_* \-\-> perl
+\&                                                       |
+\&                      event handler <\-\- call_* <\-\-\-\-+
+\&                      ...
+\&                      event handler \-\-> call_* \-\-> perl
+\&                                                       |
+\&                      event handler <\-\- call_* <\-\-\-\-+
+.Ve
+.PP
+In this case the flow of control can consist of only the repeated
+sequence
+.PP
+.Vb 1
+\&    event handler \-\-> call_* \-\-> perl
+.Ve
+.PP
+for practically the complete duration of the program.  This means that
+control may \fInever\fR drop back to the surrounding scope in Perl at the
+extreme left.
+.PP
+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 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!
+.PP
+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 dispose explicitly 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.
+.SS "Strategies for Storing Callback Context Information"
+.IX Subsection "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.
+.PP
+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 \f(CW\*(C`register_fatal\*(C'\fR which registers the C function
+to get called when a fatal error occurs.
+.PP
+.Vb 1
+\&    register_fatal(cb1);
+.Ve
+.PP
+The single parameter \f(CW\*(C`cb1\*(C'\fR is a pointer to a function, so you must
+have defined \f(CW\*(C`cb1\*(C'\fR in your code, say something like this
+.PP
+.Vb 6
+\&    static void
+\&    cb1()
+\&    {
+\&        printf ("Fatal Error\en");
+\&        exit(1);
+\&    }
+.Ve
+.PP
+Now change that to call a Perl subroutine instead
+.PP
+.Vb 1
+\&    static SV * callback = (SV*)NULL;
+\&
+\&    static void
+\&    cb1()
+\&    {
+\&        dSP;
+\&
+\&        PUSHMARK(SP);
+\&
+\&        /* Call the Perl sub to process the callback */
+\&        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);
+.Ve
+.PP
+where the Perl equivalent of \f(CW\*(C`register_fatal\*(C'\fR and the callback it
+registers, \f(CW\*(C`pcb1\*(C'\fR, might look like this
+.PP
+.Vb 2
+\&    # Register the sub pcb1
+\&    register_fatal(\e&pcb1);
+\&
+\&    sub pcb1
+\&    {
+\&        die "I\*(Aqm dying...\en";
+\&    }
+.Ve
+.PP
+The mapping between the C callback and the Perl equivalent is stored in
+the global variable \f(CW\*(C`callback\*(C'\fR.
+.PP
+This will be adequate if you ever need to have only one callback
+registered at any time. An example could be an error handler like the
+code sketched out above. Remember though, repeated calls to
+\&\f(CW\*(C`register_fatal\*(C'\fR will replace the previously registered callback
+function with the new one.
+.PP
+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.
+.PP
+Say the i/o library has a function \f(CW\*(C`asynch_read\*(C'\fR which associates a C
+function \f(CW\*(C`ProcessRead\*(C'\fR with a file handle \f(CW\*(C`fh\*(C'\fR\-\-this assumes that it
+has also provided some routine to open the file and so obtain the file
+handle.
+.PP
+.Vb 1
+\&    asynch_read(fh, ProcessRead)
+.Ve
+.PP
+This may expect the C \fIProcessRead\fR function of this form
+.PP
+.Vb 7
+\&    void
+\&    ProcessRead(fh, buffer)
+\&    int fh;
+\&    char *      buffer;
+\&    {
+\&         ...
+\&    }
+.Ve
+.PP
+To provide a Perl interface to this library we need to be able to map
+between the \f(CW\*(C`fh\*(C'\fR 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
+.PP
+.Vb 1
+\&    static HV * Mapping = (HV*)NULL;
+\&
+\&    void
+\&    asynch_read(fh, callback)
+\&        int     fh
+\&        SV *    callback
+\&        CODE:
+\&        /* If the hash doesn\*(Aqt 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);
+.Ve
+.PP
+and \f(CW\*(C`asynch_read_if\*(C'\fR could look like this
+.PP
+.Vb 7
+\&    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...\en");
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(fh)));
+\&        PUSHs(sv_2mortal(newSVpv(buffer, 0)));
+\&        PUTBACK;
+\&
+\&        /* Call the Perl sub */
+\&        call_sv(*sv, G_DISCARD);
+\&    }
+.Ve
+.PP
+For completeness, here is \f(CW\*(C`asynch_close\*(C'\fR.  This shows how to remove
+the entry from the hash \f(CW\*(C`Mapping\*(C'\fR.
+.PP
+.Vb 6
+\&    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);
+.Ve
+.PP
+So the Perl interface would look like this
+.PP
+.Vb 4
+\&    sub callback1
+\&    {
+\&        my($handle, $buffer) = @_;
+\&    }
+\&
+\&    # Register the Perl callback
+\&    asynch_read($fh, \e&callback1);
+\&
+\&    asynch_close($fh);
+.Ve
+.PP
+The mapping between the C callback and Perl is stored in the global
+hash \f(CW\*(C`Mapping\*(C'\fR this time. Using a hash has the distinct advantage that
+it allows an unlimited number of callbacks to be registered.
+.PP
+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 \f(CW\*(C`buffer\*(C'\fR parameter like this
+.PP
+.Vb 6
+\&    void
+\&    ProcessRead(buffer)
+\&    char *      buffer;
+\&    {
+\&        ...
+\&    }
+.Ve
+.PP
+Without the file handle there is no straightforward way to map from the
+C callback to the Perl subroutine.
+.PP
+In this case a possible way around this problem is to predefine a
+series of C functions to act as the interface to Perl, thus
+.PP
+.Vb 3
+\&    #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 */
+\&        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\en");
+\&
+\&        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\en", fh);
+\&
+\&        Map[index].Handle = NULL_HANDLE;
+\&        SvREFCNT_dec(Map[index].PerlSub);
+\&        Map[index].PerlSub = (SV*)NULL;
+\&
+\&        asynch_close(fh);
+.Ve
+.PP
+In this case the functions \f(CW\*(C`fn1\*(C'\fR, \f(CW\*(C`fn2\*(C'\fR, and \f(CW\*(C`fn3\*(C'\fR 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 \f(CW\*(C`Pcb\*(C'\fR to
+access the \f(CW\*(C`Map\*(C'\fR array and actually call the Perl subroutine.
+.PP
+There are some obvious disadvantages with this technique.
+.PP
+Firstly, the code is considerably more complex than with the previous
+example.
+.PP
+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
+recompiling.  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.
+.PP
+To summarize, here are a number of possible methods for you to consider
+for storing the mapping between C and the Perl callback
+.IP "1. Ignore the problem \- Allow only 1 callback" 5
+.IX 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.
+.IP "2. Create a sequence of callbacks \- hard wired limit" 5
+.IX 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.
+.IP "3. Use a parameter to map to the Perl callback" 5
+.IX 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.
+.SS "Alternate Stack Manipulation"
+.IX Subsection "Alternate Stack Manipulation"
+Although I have made use of only the \f(CW\*(C`POP*\*(C'\fR macros to access values
+returned from Perl subroutines, it is also possible to bypass these
+macros and read the stack using the \f(CW\*(C`ST\*(C'\fR macro (See perlxs for a
+full description of the \f(CW\*(C`ST\*(C'\fR macro).
+.PP
+Most of the time the \f(CW\*(C`POP*\*(C'\fR 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 \f(CW\*(C`ST\*(C'\fR macro as used when coding an XSUB is ideal
+for this purpose.
+.PP
+The code below is the example given in the section "Returning a List
+of Values" recoded to use \f(CW\*(C`ST\*(C'\fR instead of \f(CW\*(C`POP*\*(C'\fR.
+.PP
+.Vb 8
+\&    static void
+\&    call_AddSubtract2(a, b)
+\&    int a;
+\&    int b;
+\&    {
+\&        dSP;
+\&        I32 ax;
+\&        int count;
+\&
+\&        ENTER;
+\&        SAVETMPS;
+\&
+\&        PUSHMARK(SP);
+\&        EXTEND(SP, 2);
+\&        PUSHs(sv_2mortal(newSViv(a)));
+\&        PUSHs(sv_2mortal(newSViv(b)));
+\&        PUTBACK;
+\&
+\&        count = call_pv("AddSubtract", G_LIST);
+\&
+\&        SPAGAIN;
+\&        SP \-= count;
+\&        ax = (SP \- PL_stack_base) + 1;
+\&
+\&        if (count != 2)
+\&            croak("Big trouble\en");
+\&
+\&        printf ("%d + %d = %d\en", a, b, SvIV(ST(0)));
+\&        printf ("%d \- %d = %d\en", a, b, SvIV(ST(1)));
+\&
+\&        PUTBACK;
+\&        FREETMPS;
+\&        LEAVE;
+\&    }
+.Ve
+.PP
+Notes
+.IP 1. 5
+Notice that it was necessary to define the variable \f(CW\*(C`ax\*(C'\fR.  This is
+because the \f(CW\*(C`ST\*(C'\fR macro expects it to exist.  If we were in an XSUB it
+would not be necessary to define \f(CW\*(C`ax\*(C'\fR as it is already defined for
+us.
+.IP 2. 5
+The code
+.Sp
+.Vb 3
+\&        SPAGAIN;
+\&        SP \-= count;
+\&        ax = (SP \- PL_stack_base) + 1;
+.Ve
+.Sp
+sets the stack up so that we can use the \f(CW\*(C`ST\*(C'\fR macro.
+.IP 3. 5
+Unlike the original coding of this example, the returned
+values are not accessed in reverse order.  So \f(CWST(0)\fR refers to the
+first value returned by the Perl subroutine and \f(CWST(count\-1)\fR
+refers to the last.
+.SS "Creating and Calling an Anonymous Subroutine in C"
+.IX Subsection "Creating and Calling an Anonymous Subroutine in C"
+As we've already shown, \f(CW\*(C`call_sv\*(C'\fR can be used to invoke an
+anonymous subroutine.  However, our example showed a Perl script
+invoking an XSUB to perform this operation.  Let's see how it can be
+done inside our C code:
+.PP
+.Vb 1
+\& ...
+\&
+\& SV *cvrv
+\&    = eval_pv("sub {
+\&                print \*(AqYou will not find me cluttering any namespace!\*(Aq
+\&               }", TRUE);
+\&
+\& ...
+\&
+\& call_sv(cvrv, G_VOID|G_NOARGS);
+.Ve
+.PP
+\&\f(CW\*(C`eval_pv\*(C'\fR is used to compile the anonymous subroutine, which
+will be the return value as well (read more about \f(CW\*(C`eval_pv\*(C'\fR in
+"eval_pv" in perlapi).  Once this code reference is in hand, it
+can be mixed in with all the previous examples we've shown.
+.SH "LIGHTWEIGHT CALLBACKS"
+.IX Header "LIGHTWEIGHT CALLBACKS"
+Sometimes you need to invoke the same subroutine repeatedly.
+This usually happens with a function that acts on a list of
+values, such as Perl's built-in \fBsort()\fR. You can pass a
+comparison function to \fBsort()\fR, which will then be invoked
+for every pair of values that needs to be compared. The \fBfirst()\fR
+and \fBreduce()\fR functions from List::Util follow a similar
+pattern.
+.PP
+In this case it is possible to speed up the routine (often
+quite substantially) by using the lightweight callback API.
+The idea is that the calling context only needs to be
+created and destroyed once, and the sub can be called
+arbitrarily many times in between.
+.PP
+It is usual to pass parameters using global variables (typically
+\&\f(CW$_\fR for one parameter, or \f(CW$a\fR and \f(CW$b\fR for two parameters) rather
+than via \f(CW@_\fR. (It is possible to use the \f(CW@_\fR mechanism if you know
+what you're doing, though there is as yet no supported API for
+it. It's also inherently slower.)
+.PP
+The pattern of macro calls is like this:
+.PP
+.Vb 3
+\&    dMULTICALL;                 /* Declare local variables */
+\&    U8 gimme = G_SCALAR;        /* context of the call: G_SCALAR,
+\&                                 * G_LIST, or G_VOID */
+\&
+\&    PUSH_MULTICALL(cv);         /* Set up the context for calling cv,
+\&                                   and set local vars appropriately */
+\&
+\&    /* loop */ {
+\&        /* set the value(s) af your parameter variables */
+\&        MULTICALL;              /* Make the actual call */
+\&    } /* end of loop */
+\&
+\&    POP_MULTICALL;              /* Tear down the calling context */
+.Ve
+.PP
+For some concrete examples, see the implementation of the
+\&\fBfirst()\fR and \fBreduce()\fR functions of List::Util 1.18. There you
+will also find a header file that emulates the multicall API
+on older versions of perl.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlxs, perlguts, perlembed
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Marquess
+.PP
+Special thanks to the following people who assisted in the creation of
+the document.
+.PP
+Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
+and Larry Wall.
+.SH DATE
+.IX Header "DATE"
+Last updated for perl 5.23.1.