The purpose of this document is to show you how to write callbacks, i.e. how to call Perl from C. The main focus is on how to interface back to Perl from a bit of C code that has itself been run by Perl, i.e. the 'main' program is a Perl script; you are using it to execute a section of code written in C; that bit of C code wants you to do something with a particular event, so you want a Perl sub to be executed whenever it happens.
Examples where this is necessary include
A fairly common feature in applications is to allow you to define a C function that will get called whenever something nasty occurs. What we would like is for a Perl sub to be called instead.
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 perlapi manpage and the perlguts manpage .
This stuff is easier to explain using examples. But first here are a few definitions anyway.
I32 perl_call_sv(SV* sv, I32 flags) ; I32 perl_call_pv(char *subname, I32 flags) ; I32 perl_call_method(char *methname, I32 flags) ; I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;The key function is perl_call_sv. All the other functions make use of perl_call_sv to do what they do.
perl_call_sv takes two parameters, the first is an SV*. This allows you to specify the Perl sub to be called either as a C string (which has first been converted to an SV) or a reference to a sub. Example 7, shows you how you can make use of perl_call_sv. The second parameter, flags, is a general purpose option command. This parameter is common to all the perl_call_* functions. It is discussed in the next section.
The function, perl_call_pv, is similar as perl_call_sv except it expects it's first parameter has to be a C char* which identifies the Perl sub you want to call, e.g. perl_call_pv("fred", 0).
The function perl_call_method expects its first argument to contain a blessed reference to a class. Using that reference it looks up and calls methname from that class. See example 9.
perl_call_argv calls the Perl sub specified by the subname parameter. It also takes the usual flags parameter. The final parameter, argv, consists of a list of C strings to be sent to the Perl sub. See example 8.
All the functions return a number. This is a count of the number of items returned by the Perl sub on the stack.
As a general rule you should always check the return value from these functions. Even if you are only expecting a particular number of values to be returned from the Perl sub, there is nothing to stop someone from doing something unexpected - don't say you havn't been warned.
Whatever the Perl sub actually returns, we only want a scalar. If the perl sub does return a scalar, the return value from the perl_call_* function will be 1 or 0. If 1, then the value actually returned by the Perl sub will be contained on the top of the stack. If 0, then the sub has probably called die or you have used the G_DISCARD flag.
If the Perl sub returns a list, the perl_call_* function will still only return 1 or 0. If 1, then the number of elements in the list will be stored on top of the stack. The actual values of the list will not be accessable.
G_SCALAR is the default flag setting for all the functions.
The return code from the perl_call_* functions will indicate how many elements of the stack are used to store the array.
If you do not set this flag then you may need to explicitly get rid of temporary values. See example 3 for details.
A point worth noting is that if this flag is specified the Perl sub called can still access an @_ array from a previous Perl sub. This functionality can be illustrated with the perl code below
sub fred { print "@_\n" }
sub joe { &fred }
&joe(1,2,3) ;This will print
1 2 3What has happened is that fred accesses the @_ array which belongs to joe.
Whenever control returns from the perl_call_* function you need to check the $@ variable as you would in a normal Perl script. See example 6 for details of how to do this.
Perl provides many macros to assist in accessing the Perl stack. These macros should always be used when interfacing to Perl internals. Hopefully this should make the code less vulnerable to changes made to Perl in the future.
Another point worth noting is that in the first series of examples I have only made use of the perl_call_pv function. This has only been done to ease you into the topic. Wherever possible, if the choice is between using perl_call_pv and perl_call_sv, I would always try to use perl_call_sv.
The code for these examples is stored in the file F A few points to note about this example.
So the Perl sub would look like this
All the other macros which will be used in this example require you to
have used this macro.
If you are calling a Perl sub directly from an XSUB function, it is
not necessary to explicitly use the dSP macro - it will be declared for you.
The PUSHMARK macro tells Perl to make a mental note of the current stack
pointer. Even if you aren't passing any parameters (like in Example 1) you must
still call the PUSHMARK macro before you can call any of
the perl_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 perl_call_pv wouldn't
know where the two parameters we pushed were - remember that up to now
all the stack pointer manipulation we have done is with our local copy,
not the global copy.
See the section XSUB's AND THE ARGUMENT STACK in
the perlguts manpage
for
details on how the XPUSH macros work.
Here is a Perl sub, Adder, which takes 2 integer parameters and simply
returns their sum.
The FREETMPS/LEAV&/B; pair will get rid of any values returned by the Perl
sub, plus it will also dump the mortal SV's we created.
Having ENTER/SAVETMPS at the beginning
of the code makes sure that no other mortals are destroyed.
If you are making use of the Perl stack pointer in your code you must always
refresh the your local copy using SPAGAIN whenever you make use of
of the perl_call_* functions or any other Perl internal function.
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 inconsistant state. That is something you really don't want
to ever happen.
Here is the complete list of POP macros available, along with the types they
return.
Here is the Perl sub
The Perl sub, Inc, below takes 2 parameters and increments each.
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 perl_call_pv.
Consider the Perl code below
The code below for CallSub is identical to the previous time except that the
name parameter is now defined as an SV* and we use perl_call_sv instead of
perl_call_pv.
Consider the following Perl code
One of the trickiest problems to overcome when designing a callback interface
is figuring
out how to store the mapping between the C callback functions and the
Perl equivalent.
Consider the following example.
Although I have only made use of the POP* macros to access values returned
from Perl subs, it is also possible to bypass these macros and read the
stack directly.
The code below is example 4 recoded to
Special thanks to the following people who assisted in the creation of the
document.
Jeff Okamoto, Tim Bunce.
Example1: No Parameters, Nothing returned
This first trivial example will call a Perl sub, PrintUID, to print
out the UID of the process.
sub PrintUID
{
print "UID is $<\n" ;
}
and here is the C to call it
void
call_PrintUID()
{
dSP ;
PUSHMARK(sp) ;
perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
}
Simple, eh.
Example 2: Passing Parameters
Now let's make a slightly more complex example. This time we want
to call a Perl sub
which will take 2 parameters - a string ($s) and an integer ($n).
The sub will simply print the first $n characters of the string.
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 ;
PUSHMARK(sp) ;
XPUSHs(sv_2mortal(newSVpv(a, 0)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK ;
perl_call_pv("LeftString", G_DISCARD);
}
Here are a few notes on the C function call_LeftString.
Example 3: Returning a Scalar
Now for an example of dealing with the values returned from a Perl sub.
sub Adder
{
my($a, $b) = @_ ;
$a + $b ;
}
As we are now concerned with the return value from Adder, the C function
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 = perl_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
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.
Example 4: Returning a list of values
Now, let's extend the previous example to return both the sum of the parameters
and the difference.
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 = perl_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 ;
}
Notes
Example 5: 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.
sub Inc
{
++ $_[0] ;
++ $_[1] ;
}
and here is a C function to call it.
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) ;
XPUSHs(sva);
XPUSHs(svb);
PUTBACK ;
count = perl_call_pv("Inc", G_DISCARD);
if (count != 0)
croak ("call_Inc : expected 0 return value from 'Inc', got %d\n", count) ;
printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
Example 6: Using G_EVAL
Now an example using G_EVAL. Below is a Perl sub which computes the
difference of its 2 parameters. If this would result in a negative result,
the sub calls
die
.
sub Subtract
{
my ($a, $b) = @_ ;
die "death can be fatal\n" if $a < $b ;
$a - $b ;
}
and some C to call it
static void
call_Subtract(a, b)
int a ;
int b ;
{
dSP ;
int count ;
SV * sv ;
ENTER ;
SAVETMPS;
PUSHMARK(sp) ;
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK ;
count = perl_call_pv("Subtract", G_EVAL|G_SCALAR);
/* Check the eval first */
sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
if (SvTRUE(sv))
printf ("Uh oh - %s\n", SvPV(sv, na)) ;
SPAGAIN ;
if (count != 1)
croak ("call_Subtract : expected 1 return value from 'Subtract', got %d\n", count) ;
printf ("%d - %d = %d\n", a, b, POPi) ;
PUTBACK ;
FREETMPS ;
LEAVE ;
}
If call_Subtract is called thus
call_Subtract(4, 5)
the following will be printed
Uh oh - death can be fatal
Notes
sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
if (SvTRUE(sv))
printf ("Uh oh - %s\n", SvPVx(sv, na)) ;
is the equivalent of this bit of Perl
print "Uh oh - $@\n" if $@ ;
Example 7: Using perl_call_sv
In all the previous examples I have 'hard-wried' the name of the Perl sub to
be called from C.
Sometimes though, it is necessary to be able to specify the name
of the Perl sub from within the Perl script.
sub fred
{
print "Hello there\n" ;
}
CallSub("fred") ;
here is a snippet of XSUB which defines CallSub.
void
CallSub(name)
char * name
CODE:
PUSHMARK(sp) ;
perl_call_pv(name, G_DISCARD|G_NOARGS) ;
That is fine as far as it goes. The thing is, it only allows the Perl sub to be
specified as a string.
For perl 4 this was adequate, but Perl 5 allows references to
subs and anonymous subs. This is where perl_call_sv is useful.
void
CallSub(name)
SV* name
CODE:
PUSHMARK(sp) ;
perl_call_sv(name, G_DISCARD|G_NOARGS) ;
As we are using an SV to call fred the following can all be used
CallSub("fred") ;
Callsub(\&fred) ;
$ref = \&fred ;
CallSub($ref) ;
CallSub( sub { print "Hello there\n" } ) ;
As you can see, perl_call_sv gives you greater flexibility in how you
can specify the Perl sub.
Example 8: Using perl_call_argv
Here is a Perl sub which prints whatever parameters are passed to it.
sub PrintList
{
my(@list) = @_ ;
foreach (@list) { print "$_\n" }
}
and here is an example of perl_call_argv which will call PrintList.
call_PrintList
{
dSP ;
char * words[] = {"alpha", "beta", "gamma", "delta", NULL } ;
perl_call_argv("PrintList", words, G_DISCARD) ;
}
Note that it is not necessary to call PUSHMARK in this instance. This is
because perl_call_argv will do it for you.
Example 9: Using perl_call_method
[This section is under construction]
{
package Mine ;
sub new { bless [@_] }
sub Display { print $_[0][1], "\n" }
}
$a = new Mine ('red', 'green', 'blue') ;
call_Display($a, 'Display') ;
The method Display just prints out the first element of the list.
Here is a XSUB implementation of call_Display.
void
call_Display(ref, method)
SV * ref
char * method
CODE:
PUSHMARK(sp);
XPUSHs(ref);
PUTBACK;
perl_call_method(method, G_DISCARD) ;
Strategies for storing Context Information
[This section is under construction]
Alternate Stack Manipulation
[This section is under construction]
SEE ALSO
the perlapi manpage
,
the perlguts manpage
,
the perlembed manpage
AUTHOR
Paul Marquess <pmarquess@bfsec.bt.co.uk>
DATE
Version 0.4, 17th October 1994