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
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.
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.
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.
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 perlcall.tar. (Once this document settles down, all the example code will be available in the file).
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.
A few points to note about this example.
So the Perl sub 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 ;
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.
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 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.
Here is a Perl sub, Adder, which takes 2 integer parameters and simply returns their sum.
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.
The FREETMPS/LEAVE 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.
Here is the Perl sub
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
The Perl sub, Inc, below takes 2 parameters and increments each.
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)) ;
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.
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 $@ ;
Consider the Perl code below
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.
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.
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.
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.
Consider the following Perl code
{
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) ;
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.