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

=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.