source: trunk/essentials/dev-lang/perl/pod/perlcall.pod@ 3298

=head1 NAME

perlcall - Perl calling conventions from C

=head1 DESCRIPTION

The purpose of this document is to show you how to call Perl subroutines
directly from C, i.e., how to write I<callbacks>.

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 callbacks are necessary include

=over 5

=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 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 * An Event Driven Program

The classic example of where callbacks are used is when writing an
event driven program like for an X windows 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.

=back

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<perlxs> and L<perlguts>.

=head1 THE CALL_ FUNCTIONS

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 that allow you to call Perl
subroutines.  They are

    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, register char **argv);

The key function is I<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<call_sv>
to invoke the Perl subroutine.

All the I<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 call_sv

I<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 call_sv>, shows how you can make
use of I<call_sv>.

=item call_pv

The function, I<call_pv>, is similar to I<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<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 call_method

The function I<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 call_method> for an example
of using I<call_method>.

=item call_argv

I<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 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<call_*> functions is a bit mask
which can consist of any combination of the symbols defined below,
OR'ed together.


=head2  G_VOID

Calls the Perl subroutine in a void context.

This flag has 2 effects:

=over 5

=item 1.

It indicates to the subroutine being called that it is executing in
a void context (if it executes I<wantarray> the result will be the
undefined value).

=item 2.

It ensures that nothing is actually returned from the subroutine.

=back

The value returned by the I<call_*> function indicates how many
items have been returned by the Perl subroutine - in this case it will
be 0.


=head2  G_SCALAR

Calls the Perl subroutine in a scalar context.  This is the default
context flag setting for all the I<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).

=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<call_*> function indicates how many
items have been returned by the Perl subroutine - in this case it will
be either 0 or 1.

If 0, then you have specified the G_DISCARD flag.

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<call_*> function.  The section I<Returning a list in a scalar
context> shows an example of this behavior.


=head2 G_ARRAY

Calls the Perl subroutine in a list context.

As with G_SCALAR, this flag has 2 effects:

=over 5

=item 1.

It indicates to the subroutine being called that it is executing in a
list context (if it executes I<wantarray> the result will be true).


=item 2.

It ensures that all items returned from the subroutine will be
accessible when control returns from the I<call_*> function.

=back

The value returned by the I<call_*> function indicates how many
items have been returned by the Perl subroutine.

If 0, then you have specified the G_DISCARD flag.

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.

=head2 G_DISCARD

By default, the I<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 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
dispose of these temporaries explicitly 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.

=head2 G_NOARGS

Whenever a Perl subroutine is called using one of the I<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.

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.

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<call_*> function has
itself been called from another Perl subroutine. The code below
illustrates this

    sub fred
      { print "@_\n"  }

    sub joe
      { &fred }

    &joe(1,2,3);

This will print

    1 2 3

What has happened is that C<fred> accesses the C<@_> array which
belongs to C<joe>.


=head2 G_EVAL

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 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 I<eval { }>
around the subroutine call.

Whenever control returns from the I<call_*> function you need to
check the C<$@> variable as you would in a normal Perl script.

The value returned from the I<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<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 on using G_EVAL.

=head2 G_KEEPERR

You may have noticed that using the G_EVAL flag described above will
B<always> clear the C<$@> variable and set it to a string describing
the error iff there was an error in the called code.  This unqualified
resetting of C<$@> can be problematic in the reliable identification of
errors using the C<eval {}> mechanism, because the possibility exists
that perl will call other code (end of block processing code, for
example) between the time the error causes C<$@> to be set within
C<eval {}>, and the subsequent statement which checks for the value of
C<$@> gets executed in the user's script.

This scenario will mostly be applicable to code that is meant to be
called from within destructors, asynchronous callbacks, signal
handlers, C<__DIE__> or C<__WARN__> hooks, and C<tie> functions.  In
such situations, you will not want to clear C<$@> at all, but simply to
append any new errors to any existing value of C<$@>.

The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
I<call_*> functions that are used to implement such code.  This flag
has no effect when G_EVAL is not used.

When G_KEEPERR is used, any errors in the called code will be prefixed
with the string "\t(in cleanup)", and appended to the current value
of C<$@>.  an error will not be appended if that same error string is
already at the end of C<$@>.

In addition, a warning is generated using the appended string. This can be
disabled using C<no warnings 'misc'>.

The G_KEEPERR flag was introduced in Perl version 5.002.

See I<Using G_KEEPERR> for an example of a situation that warrants the
use of this flag.

=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_V> macro, which returns
C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
in a scalar context, or C<G_VOID> if in a void context (i.e. the
return value will not be used).  An older version of this macro is
called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
C<G_VOID>.  An example of using the C<GIMME_V> macro is shown in
section I<Using GIMME_V>.

=head1 EXAMPLES

Enough of the definition talk, let's have a few examples.

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.

Another point worth noting is that in the first series of examples I
have made use of only the I<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<call_pv> and
I<call_sv>, you should always try to use I<call_sv>.  See
I<Using call_sv> for details.

=head2 No Parameters, Nothing returned

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 a C function to call it

    static void
    call_PrintUID()
    {
        dSP;

        PUSHMARK(SP);
        call_pv("PrintUID", G_DISCARD|G_NOARGS);
    }

Simple, eh.

A few points to note about this example.

=over 5

=item 1.

Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
the next example.

=item 2.

We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
specified.

=item 3.

We aren't interested in anything returned from I<PrintUID>, so
G_DISCARD is specified. Even if I<PrintUID> was changed to
return some value(s), having specified G_DISCARD will mean that they
will be wiped by the time control returns from I<call_pv>.

=item 4.

As I<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.

Because we specified G_DISCARD, it is not necessary to check the value
returned from I<call_pv>. It will always be 0.

=back

=head2 Passing Parameters

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 ($s) and an integer ($n).  The subroutine will simply
print the first $n characters of the string.

So the Perl subroutine would look like this

    sub LeftString
    {
        my($s, $n) = @_;
        print substr($s, 0, $n), "\n";
    }

The C function required to call I<LeftString> would look like this.

    static void
    call_LeftString(a, b)
    char * a;
    int b;
    {