|
perlcall - Perl calling conventions from C
The purpose of this document is to show you how to call Perl subroutines
directly from C, i.e., how to write 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
- 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.
- 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.
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
the perlembed manpage.
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 -
the perlxs manpage and the perlguts manpage.
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 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 call_sv
to invoke the Perl subroutine.
All the call_* functions have a 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 FLAG VALUES.
Each of the functions will now be discussed in turn.
- call_sv
-
call_sv takes two parameters, the first, 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, Using call_sv, shows how you can make
use of call_sv.
- call_pv
-
The function, call_pv, is similar to call_sv except it
expects its first parameter to be a C char* which identifies the Perl
subroutine you want to call, e.g., 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., "pkg::fred".
- call_method
-
The function call_method is used to call a method from a Perl
class. The parameter 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 the perlobj manpage for more information on
static and virtual methods and Using call_method for an example
of using call_method.
- call_argv
-
call_argv calls the Perl subroutine specified by the C string
stored in the subname parameter. It also takes the usual flags
parameter. The final parameter, argv, consists of a NULL terminated
list of C strings to be passed as parameters to the Perl subroutine.
See Using call_argv.
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 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.
The flags parameter in all the call_* functions is a bit mask
which can consist of any combination of the symbols defined below,
OR'ed together.
Calls the Perl subroutine in a void context.
This flag has 2 effects:
-
It indicates to the subroutine being called that it is executing in
a void context (if it executes wantarray the result will be the
undefined value).
-
It ensures that nothing is actually returned from the subroutine.
The value returned by the call_* function indicates how many
items have been returned by the Perl subroutine - in this case it will
be 0.
Calls the Perl subroutine in a scalar context. This is the default
context flag setting for all the call_* functions.
This flag has 2 effects:
-
It indicates to the subroutine being called that it is executing in a
scalar context (if it executes wantarray the result will be false).
-
It ensures that only a scalar is actually returned from the subroutine.
The subroutine can, of course, ignore the wantarray and return a
list anyway. If so, then only the last element of the list will be
returned.
The value returned by the 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 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
call_* function. The section Returning a list in a scalar
context shows an example of this behavior.
Calls the Perl subroutine in a list context.
As with G_SCALAR, this flag has 2 effects:
-
It indicates to the subroutine being called that it is executing in a
list context (if it executes wantarray the result will be true).
-
It ensures that all items returned from the subroutine will be
accessible when control returns from the call_* function.
The value returned by the 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 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.
By default, the 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 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 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.
Whenever a Perl subroutine is called using one of the 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 @_ 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 @_ array from a previous Perl subroutine. This will
occur when the code that is executing the 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 fred accesses the @_ array which
belongs to joe.
It is possible for the Perl subroutine you are calling to terminate
abnormally, e.g., by calling 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 eval { }
around the subroutine call.
Whenever control returns from the call_* function you need to
check the $@ variable as you would in a normal Perl script.
The value returned from the 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:
-
If the call_* function returns normally, then the value
returned is as specified in the previous sections.
-
If G_DISCARD is specified, the return value will always be 0.
-
If G_ARRAY is specified and an error has occurred, the return value
will always be 0.
-
If G_SCALAR is specified and an error has occurred, the return value
will be 1 and the value on the top of the stack will be undef. This
means that if you have already detected the error by checking $@ and
you want the program to continue, you must remember to pop the undef
from the stack.
See Using G_EVAL for details on using G_EVAL.
You may have noticed that using the G_EVAL flag described above will
always clear the $@ variable and set it to a string describing
the error iff there was an error in the called code. This unqualified
resetting of $@ can be problematic in the reliable identification of
errors using the 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 $@ to be set within
eval {}, and the subsequent statement which checks for the value of
$@ 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, __DIE__ or __WARN__ hooks, and tie functions. In
such situations, you will not want to clear $@ at all, but simply to
append any new errors to any existing value of $@.
The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
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 $@. an error will not be appended if that same error string is
already at the end of $@.
In addition, a warning is generated using the appended string. This can be
disabled using no warnings 'misc'.
The G_KEEPERR flag was introduced in Perl version 5.002.
See Using G_KEEPERR for an example of a situation that warrants the
use of this flag.
As mentioned above, you can determine the context of the currently
executing subroutine in Perl with wantarray. The equivalent test
can be made in C by using the GIMME_V macro, which returns
G_ARRAY if you have been called in a list context, G_SCALAR if
in a scalar context, or G_VOID if in a void context (i.e. the
return value will not be used). An older version of this macro is
called GIMME; in a void context it returns G_SCALAR instead of
G_VOID. An example of using the GIMME_V macro is shown in
section Using GIMME_V.
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 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 call_pv and
call_sv, you should always try to use call_sv. See
Using call_sv for details.
This first trivial example will call a Perl subroutine, 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.
-
Ignore dSP and PUSHMARK(SP) for now. They will be discussed in
the next example.
-
We aren't passing any parameters to PrintUID so G_NOARGS can be
specified.
-
We aren't interested in anything returned from PrintUID, so
G_DISCARD is specified. Even if 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 call_pv.
-
As 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.
-
Because we specified G_DISCARD, it is not necessary to check the value
returned from call_pv. It will always be 0.
Now let's make a slightly more complex example. This time we want to
call a Perl subroutine, 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 LeftString would look like this.
static void
call_LeftString(a, b)
char * a;
int b;
{
dSP;
ENTER;
SAVETMPS;
PUSHMARK(SP);
XPUSHs(sv_2mortal(newSVpv(a, 0)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK;
call_pv("LeftString", G_DISCARD);
FREETMPS;
LEAVE;
}
Here are a few notes on the C function call_LeftString.
-
Parameters are passed to the Perl subroutine using the Perl stack.
This is the purpose of the code beginning with the line dSP and
ending with the line PUTBACK. The dSP declares a local copy
of the stack pointer. This local copy should always be accessed
as SP.
-
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 dSP--it declares
and initializes a 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.
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 dSP macro explicitly--it will be declared for you
automatically.
-
Any parameters to be pushed onto the stack should be bracketed by the
PUSHMARK and PUTBACK 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 @_ array for the
subroutine, it knows how big to make it.
The 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 No Parameters, Nothing returned) you
must still call the PUSHMARK macro before you can call any of the
call_* functions--Perl still needs to know that there are no
parameters.
The PUTBACK macro sets the global copy of the stack pointer to be
the same as our local copy. If we didn't do this 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, not the global copy.
-
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.
See XSUBs and the Argument Stack in the perlguts manpage for details
on how the XPUSH macros work.
-
Because we created temporary values (by means of sv_2mortal() calls)
we will have to tidy up the Perl stack and dispose of mortal SVs.
This is the purpose of
ENTER;
SAVETMPS;
at the start of the function, and
FREETMPS;
LEAVE;
at the end. The ENTER/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 FREETMPS/LEAVE 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 ENTER/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 { and } in Perl
to limit the scope of local variables.
See the section Using Perl to dispose of temporaries for details of
an alternative to using these macros.
-
Finally, LeftString can now be called via the call_pv 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.
Now for an example of dealing with the items returned from a Perl
subroutine.
Here is a Perl subroutine, Adder, that takes 2 integer parameters
and simply returns their sum.
sub Adder
{
my($a, $b) = @_;
$a + $b;
}
Because we are now concerned with the return value from Adder, the C
function required to call it is now a bit more complex.
static void
call_Adder(a, b)
int a;
int b;
{
dSP;
int count;
ENTER;
SAVETMPS;
PUSHMARK(SP);
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK;
count = call_pv("Adder", G_SCALAR);
SPAGAIN;
if (count != 1)
croak("Big trouble\n");
printf ("The sum of %d and %d is %d\n", a, b, POPi);
PUTBACK;
FREETMPS;
LEAVE;
}
Points to note this time are
-
The only flag specified this time was G_SCALAR. That means the @_
array will be created and that the value returned by Adder will
still exist after the call to call_pv.
-
The purpose of the macro 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 reallocated whilst in the
call_pv call.
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 call_* functions or any other Perl internal function.
-
Although only a single value was expected to be returned from Adder,
it is still good practice to check the return code from call_pv
anyway.
Expecting a single value is not quite the same as knowing that there
will be one. If someone modified 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
really don't want to happen ever.
-
The POPi macro is used here to pop the return value from the stack.
In this case we wanted an integer, so POPi was used.
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
-
The final 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 POPi it updated only our
local copy of the stack pointer. Remember, PUTBACK sets the global
stack pointer to be the same as our local copy.
Now, let's extend the previous example to return both the sum of the
parameters and the difference.
Here is the Perl subroutine
sub AddSubtract
{
my($a, $b) = @_;
($a+$b, $a-$b);
}
and this is the C function
static void
call_AddSubtract(a, b)
int a;
int b;
{
dSP;
int count;
ENTER;
SAVETMPS;
PUSHMARK(SP);
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK;
count = call_pv("AddSubtract", G_ARRAY);
SPAGAIN;
if (count != 2)
croak("Big trouble\n");
printf ("%d - %d = %d\n", a, b, POPi);
printf ("%d + %d = %d\n", a, b, POPi);
PUTBACK;
FREETMPS;
LEAVE;
}
If call_AddSubtract is called like this
call_AddSubtract(7, 4);
then here is the output
7 - 4 = 3
7 + 4 = 11
Notes
-
We wanted list context, so G_ARRAY was used.
-
Not surprisingly 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 POP* macros they come off the stack in reverse
order.
Say the Perl subroutine in the previous section was called in a scalar
context, like this
static void
call_AddSubScalar(a, b)
int a;
in | 
