3 perlcall - Perl calling conventions from C
7 The purpose of this document is to show you how to call Perl subroutines
8 directly from C, i.e. how to write I<callbacks>.
10 Apart from discussing the C interface provided by Perl for writing
11 callbacks the document uses a series of examples to show how the
12 interface actually works in practice. In addition some techniques for
13 coding callbacks are covered.
15 Examples where callbacks are necessary include
19 =item * An Error Handler
21 You have created an XSUB interface to an application's C API.
23 A fairly common feature in applications is to allow you to define a C
24 function that will be called whenever something nasty occurs. What we
25 would like is to be able to specify a Perl subroutine that will be
28 =item * An Event Driven Program
30 The classic example of where callbacks are used is when writing an
31 event driven program like for an X windows application. In this case
32 your register functions to be called whenever specific events occur,
33 e.g. a mouse button is pressed, the cursor moves into a window or a
34 menu item is selected.
38 Although the techniques described here are applicable when embedding
39 Perl in a C program, this is not the primary goal of this document.
40 There are other details that must be considered and are specific to
41 embedding Perl. For details on embedding Perl in C refer to
44 Before you launch yourself head first into the rest of this document,
45 it would be a good idea to have read the following two documents -
46 L<perlapi> and L<perlguts>.
48 =head1 THE PERL_CALL FUNCTIONS
50 Although this stuff is easier to explain using examples, you first need
51 be aware of a few important definitions.
53 Perl has a number of C functions that allow you to call Perl
56 I32 perl_call_sv(SV* sv, I32 flags) ;
57 I32 perl_call_pv(char *subname, I32 flags) ;
58 I32 perl_call_method(char *methname, I32 flags) ;
59 I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;
61 The key function is I<perl_call_sv>. All the other functions are
62 fairly simple wrappers which make it easier to call Perl subroutines in
63 special cases. At the end of the day they will all call I<perl_call_sv>
64 to actually invoke the Perl subroutine.
66 All the I<perl_call_*> functions have a C<flags> parameter which is
67 used to pass a bit mask of options to Perl. This bit mask operates
68 identically for each of the functions. The settings available in the
69 bit mask are discussed in L<FLAG VALUES>.
71 Each of the functions will now be discussed in turn.
77 I<perl_call_sv> takes two parameters, the first, C<sv>, is an SV*.
78 This allows you to specify the Perl subroutine to be called either as a
79 C string (which has first been converted to an SV) or a reference to a
80 subroutine. The section, I<Using perl_call_sv>, shows how you can make
81 use of I<perl_call_sv>.
85 The function, I<perl_call_pv>, is similar to I<perl_call_sv> except it
86 expects its first parameter to be a C char* which identifies the Perl
87 subroutine you want to call, e.g. C<perl_call_pv("fred", 0)>. If the
88 subroutine you want to call is in another package, just include the
89 package name in the string, e.g. C<"pkg::fred">.
91 =item B<perl_call_method>
93 The function I<perl_call_method> is used to call a method from a Perl
94 class. The parameter C<methname> corresponds to the name of the method
95 to be called. Note that the class that the method belongs to is passed
96 on the Perl stack rather than in the parameter list. This class can be
97 either the name of the class (for a static method) or a reference to an
98 object (for a virtual method). See L<perlobj> for more information on
99 static and virtual methods and L<Using perl_call_method> for an example
100 of using I<perl_call_method>.
102 =item B<perl_call_argv>
104 I<perl_call_argv> calls the Perl subroutine specified by the C string
105 stored in the C<subname> parameter. It also takes the usual C<flags>
106 parameter. The final parameter, C<argv>, consists of a NULL terminated
107 list of C strings to be passed as parameters to the Perl subroutine.
108 See I<Using perl_call_argv>.
112 All the functions return an integer. This is a count of the number of
113 items returned by the Perl subroutine. The actual items returned by the
114 subroutine are stored on the Perl stack.
116 As a general rule you should I<always> check the return value from
117 these functions. Even if you are expecting only a particular number of
118 values to be returned from the Perl subroutine, there is nothing to
119 stop someone from doing something unexpected - don't say you haven't
124 The C<flags> parameter in all the I<perl_call_*> functions is a bit mask
125 which can consist of any combination of the symbols defined below,
131 Calls the Perl subroutine in a scalar context. This is the default
132 context flag setting for all the I<perl_call_*> functions.
134 This flag has 2 effects
140 it indicates to the subroutine being called that it is executing in a
141 scalar context (if it executes I<wantarray> the result will be false).
146 it ensures that only a scalar is actually returned from the subroutine.
147 The subroutine can, of course, ignore the I<wantarray> and return a
148 list anyway. If so, then only the last element of the list will be
153 The value returned by the I<perl_call_*> function indicates how may
154 items have been returned by the Perl subroutine - in this case it will
157 If 0, then you have specified the G_DISCARD flag.
159 If 1, then the item actually returned by the Perl subroutine will be
160 stored on the Perl stack - the section I<Returning a Scalar> shows how
161 to access this value on the stack. Remember that regardless of how
162 many items the Perl subroutine returns, only the last one will be
163 accessible from the stack - think of the case where only one value is
164 returned as being a list with only one element. Any other items that
165 were returned will not exist by the time control returns from the
166 I<perl_call_*> function. The section I<Returning a list in a scalar
167 context> shows an example of this behaviour.
172 Calls the Perl subroutine in a list context.
174 As with G_SCALAR, this flag has 2 effects
180 it indicates to the subroutine being called that it is executing in an
181 array context (if it executes I<wantarray> the result will be true).
186 it ensures that all items returned from the subroutine will be
187 accessible when control returns from the I<perl_call_*> function.
191 The value returned by the I<perl_call_*> function indicates how may
192 items have been returned by the Perl subroutine.
194 If 0, the you have specified the G_DISCARD flag.
196 If not 0, then it will be a count of the number of items returned by
197 the subroutine. These items will be stored on the Perl stack. The
198 section I<Returning a list of values> gives an example of using the
199 G_ARRAY flag and the mechanics of accessing the returned items from the
204 By default, the I<perl_call_*> functions place the items returned from
205 by the Perl subroutine on the stack. If you are not interested in
206 these items, then setting this flag will make Perl get rid of them
207 automatically for you. Note that it is still possible to indicate a
208 context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
210 If you do not set this flag then it is I<very> important that you make
211 sure that any temporaries (i.e. parameters passed to the Perl
212 subroutine and values returned from the subroutine) are disposed of
213 yourself. The section I<Returning a Scalar> gives details of how to
214 explicitly dispose of these temporaries and the section I<Using Perl to
215 dispose of temporaries> discusses the specific circumstances where you
216 can ignore the problem and let Perl deal with it for you.
220 Whenever a Perl subroutine is called using one of the I<perl_call_*>
221 functions, it is assumed by default that parameters are to be passed to
222 the subroutine. If you are not passing any parameters to the Perl
223 subroutine, you can save a bit of time by setting this flag. It has
224 the effect of not creating the C<@_> array for the Perl subroutine.
226 Although the functionality provided by this flag may seem
227 straightforward, it should be used only if there is a good reason to do
228 so. The reason for being cautious is that even if you have specified
229 the G_NOARGS flag, it is still possible for the Perl subroutine that
230 has been called to think that you have passed it parameters.
232 In fact, what can happen is that the Perl subroutine you have called
233 can access the C<@_> array from a previous Perl subroutine. This will
234 occur when the code that is executing the I<perl_call_*> function has
235 itself been called from another Perl subroutine. The code below
250 What has happened is that C<fred> accesses the C<@_> array which
256 It is possible for the Perl subroutine you are calling to terminate
257 abnormally, e.g. by calling I<die> explicitly or by not actually
258 existing. By default, when either of these of events occurs, the
259 process will terminate immediately. If though, you want to trap this
260 type of event, specify the G_EVAL flag. It will put an I<eval { }>
261 around the subroutine call.
263 Whenever control returns from the I<perl_call_*> function you need to
264 check the C<$@> variable as you would in a normal Perl script.
266 The value returned from the I<perl_call_*> function is dependent on
267 what other flags have been specified and whether an error has
268 occurred. Here are all the different cases that can occur
274 If the I<perl_call_*> function returns normally, then the value
275 returned is as specified in the previous sections.
279 If G_DISCARD is specified, the return value will always be 0.
283 If G_ARRAY is specified I<and> an error has occurred, the return value
288 If G_SCALAR is specified I<and> an error has occurred, the return value
289 will be 1 and the value on the top of the stack will be I<undef>. This
290 means that if you have already detected the error by checking C<$@> and
291 you want the program to continue, you must remember to pop the I<undef>
296 See I<Using G_EVAL> for details of using G_EVAL.
298 =head2 Determining the Context
300 As mentioned above, you can determine the context of the currently
301 executing subroutine in Perl with I<wantarray>. The equivalent test can
302 be made in C by using the C<GIMME> macro. This will return C<G_SCALAR>
303 if you have been called in a scalar context and C<G_ARRAY> if in an
304 array context. An example of using the C<GIMME> macro is shown in
305 section I<Using GIMME>.
307 =head1 KNOWN PROBLEMS
309 This section outlines all known problems that exist in the
310 I<perl_call_*> functions.
316 If you are intending to make use of both the G_EVAL and G_SCALAR flags
317 in your code, use a version of Perl greater than 5.000. There is a bug
318 in version 5.000 of Perl which means that the combination of these two
319 flags will not work as described in the section I<FLAG VALUES>.
321 Specifically, if the two flags are used when calling a subroutine and
322 that subroutine does not call I<die>, the value returned by
323 I<perl_call_*> will be wrong.
328 In Perl 5.000 and 5.001 there is a problem with using I<perl_call_*> if
329 the Perl sub you are calling attempts to trap a I<die>.
331 The symptom of this problem is that the called Perl sub will continue
332 to completion, but whenever it attempts to pass control back to the
333 XSUB, the program will immediately terminate.
335 For example, say you want to call this Perl sub
339 eval { die "Fatal Error" ; }
340 print "Trapped error: $@\n"
350 perl_call_pv("fred", G_DISCARD|G_NOARGS) ;
351 fprintf(stderr, "back in Call_fred\n") ;
353 When C<Call_fred> is executed it will print
355 Trapped error: Fatal Error
357 As control never returns to C<Call_fred>, the C<"back in Call_fred">
358 string will not get printed.
360 To work around this problem, you can either upgrade to Perl 5.002 (or
361 later), or use the G_EVAL flag with I<perl_call_*> as shown below
367 perl_call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ;
368 fprintf(stderr, "back in Call_fred\n") ;
376 Enough of the definition talk, let's have a few examples.
378 Perl provides many macros to assist in accessing the Perl stack.
379 Wherever possible, these macros should always be used when interfacing
380 to Perl internals. Hopefully this should make the code less vulnerable
381 to any changes made to Perl in the future.
383 Another point worth noting is that in the first series of examples I
384 have made use of only the I<perl_call_pv> function. This has been done
385 to keep the code simpler and ease you into the topic. Wherever
386 possible, if the choice is between using I<perl_call_pv> and
387 I<perl_call_sv>, you should always try to use I<perl_call_sv>. See
388 I<Using perl_call_sv> for details.
390 =head2 No Parameters, Nothing returned
392 This first trivial example will call a Perl subroutine, I<PrintUID>, to
393 print out the UID of the process.
397 print "UID is $<\n" ;
400 and here is a C function to call it
408 perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
413 A few points to note about this example.
419 Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in
424 We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
429 We aren't interested in anything returned from I<PrintUID>, so
430 G_DISCARD is specified. Even if I<PrintUID> was changed to actually
431 return some value(s), having specified G_DISCARD will mean that they
432 will be wiped by the time control returns from I<perl_call_pv>.
436 As I<perl_call_pv> is being used, the Perl subroutine is specified as a
437 C string. In this case the subroutine name has been 'hard-wired' into the
442 Because we specified G_DISCARD, it is not necessary to check the value
443 returned from I<perl_call_pv>. It will always be 0.
447 =head2 Passing Parameters
449 Now let's make a slightly more complex example. This time we want to
450 call a Perl subroutine, C<LeftString>, which will take 2 parameters - a
451 string (C<$s>) and an integer (C<$n>). The subroutine will simply
452 print the first C<$n> characters of the string.
454 So the Perl subroutine would look like this
459 print substr($s, 0, $n), "\n" ;
462 The C function required to call I<LeftString> would look like this.
465 call_LeftString(a, b)
472 XPUSHs(sv_2mortal(newSVpv(a, 0)));
473 XPUSHs(sv_2mortal(newSViv(b)));
476 perl_call_pv("LeftString", G_DISCARD);
479 Here are a few notes on the C function I<call_LeftString>.
485 Parameters are passed to the Perl subroutine using the Perl stack.
486 This is the purpose of the code beginning with the line C<dSP> and
487 ending with the line C<PUTBACK>.
492 If you are going to put something onto the Perl stack, you need to know
493 where to put it. This is the purpose of the macro C<dSP> - it declares
494 and initializes a I<local> copy of the Perl stack pointer.
496 All the other macros which will be used in this example require you to
497 have used this macro.
499 The exception to this rule is if you are calling a Perl subroutine
500 directly from an XSUB function. In this case it is not necessary to
501 explicitly use the C<dSP> macro - it will be declared for you
506 Any parameters to be pushed onto the stack should be bracketed by the
507 C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
508 this context, is to automatically count the number of parameters you
509 are pushing. Then whenever Perl is creating the C<@_> array for the
510 subroutine, it knows how big to make it.
512 The C<PUSHMARK> macro tells Perl to make a mental note of the current
513 stack pointer. Even if you aren't passing any parameters (like the
514 example shown in the section I<No Parameters, Nothing returned>) you
515 must still call the C<PUSHMARK> macro before you can call any of the
516 I<perl_call_*> functions - Perl still needs to know that there are no
519 The C<PUTBACK> macro sets the global copy of the stack pointer to be
520 the same as our local copy. If we didn't do this I<perl_call_pv>
521 wouldn't know where the two parameters we pushed were - remember that
522 up to now all the stack pointer manipulation we have done is with our
523 local copy, I<not> the global copy.
527 The only flag specified this time is G_DISCARD. Since we are passing 2
528 parameters to the Perl subroutine this time, we have not specified
533 Next, we come to XPUSHs. This is where the parameters actually get
534 pushed onto the stack. In this case we are pushing a string and an
537 See the section L<perlguts/"XSUB'S and the Argument Stack"> for details
538 on how the XPUSH macros work.
542 Finally, I<LeftString> can now be called via the I<perl_call_pv>
547 =head2 Returning a Scalar
549 Now for an example of dealing with the items returned from a Perl
552 Here is a Perl subroutine, I<Adder>, which takes 2 integer parameters
553 and simply returns their sum.
561 Since we are now concerned with the return value from I<Adder>, the C
562 function required to call it is now a bit more complex.
576 XPUSHs(sv_2mortal(newSViv(a)));
577 XPUSHs(sv_2mortal(newSViv(b)));
580 count = perl_call_pv("Adder", G_SCALAR);
585 croak("Big trouble\n") ;
587 printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
594 Points to note this time are
600 The only flag specified this time was G_SCALAR. That means the C<@_>
601 array will be created and that the value returned by I<Adder> will
602 still exist after the call to I<perl_call_pv>.
608 Because we are interested in what is returned from I<Adder> we cannot
609 specify G_DISCARD. This means that we will have to tidy up the Perl
610 stack and dispose of any temporary values ourselves. This is the
616 at the start of the function, and
621 at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
622 temporaries we create. This means that the temporaries we get rid of
623 will be limited to those which were created after these calls.
625 The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
626 the Perl subroutine, plus it will also dump the mortal SV's we have
627 created. Having C<ENTER>/C<SAVETMPS> at the beginning of the code
628 makes sure that no other mortals are destroyed.
630 Think of these macros as working a bit like using C<{> and C<}> in Perl
631 to limit the scope of local variables.
633 See the section I<Using Perl to dispose of temporaries> for details of
634 an alternative to using these macros.
638 The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
639 stack pointer. This is necessary because it is possible that the memory
640 allocated to the Perl stack has been re-allocated whilst in the
641 I<perl_call_pv> call.
643 If you are making use of the Perl stack pointer in your code you must
644 always refresh the your local copy using SPAGAIN whenever you make use
645 of the I<perl_call_*> functions or any other Perl internal function.
649 Although only a single value was expected to be returned from I<Adder>,
650 it is still good practice to check the return code from I<perl_call_pv>
653 Expecting a single value is not quite the same as knowing that there
654 will be one. If someone modified I<Adder> to return a list and we
655 didn't check for that possibility and take appropriate action the Perl
656 stack would end up in an inconsistent state. That is something you
657 I<really> don't want to ever happen.
661 The C<POPi> macro is used here to pop the return value from the stack.
662 In this case we wanted an integer, so C<POPi> was used.
665 Here is the complete list of POP macros available, along with the types
676 The final C<PUTBACK> is used to leave the Perl stack in a consistent
677 state before exiting the function. This is necessary because when we
678 popped the return value from the stack with C<POPi> it updated only our
679 local copy of the stack pointer. Remember, C<PUTBACK> sets the global
680 stack pointer to be the same as our local copy.
685 =head2 Returning a list of values
687 Now, let's extend the previous example to return both the sum of the
688 parameters and the difference.
690 Here is the Perl subroutine
698 and this is the C function
701 call_AddSubtract(a, b)
712 XPUSHs(sv_2mortal(newSViv(a)));
713 XPUSHs(sv_2mortal(newSViv(b)));
716 count = perl_call_pv("AddSubtract", G_ARRAY);
721 croak("Big trouble\n") ;
723 printf ("%d - %d = %d\n", a, b, POPi) ;
724 printf ("%d + %d = %d\n", a, b, POPi) ;
731 If I<call_AddSubtract> is called like this
733 call_AddSubtract(7, 4) ;
735 then here is the output
746 We wanted array context, so G_ARRAY was used.
750 Not surprisingly C<POPi> is used twice this time because we were
751 retrieving 2 values from the stack. The important thing to note is that
752 when using the C<POP*> macros they come off the stack in I<reverse>
757 =head2 Returning a list in a scalar context
759 Say the Perl subroutine in the previous section was called in a scalar
763 call_AddSubScalar(a, b)
775 XPUSHs(sv_2mortal(newSViv(a)));
776 XPUSHs(sv_2mortal(newSViv(b)));
779 count = perl_call_pv("AddSubtract", G_SCALAR);
783 printf ("Items Returned = %d\n", count) ;
785 for (i = 1 ; i <= count ; ++i)
786 printf ("Value %d = %d\n", i, POPi) ;
793 The other modification made is that I<call_AddSubScalar> will print the
794 number of items returned from the Perl subroutine and their value (for
795 simplicity it assumes that they are integer). So if
796 I<call_AddSubScalar> is called
798 call_AddSubScalar(7, 4) ;
800 then the output will be
805 In this case the main point to note is that only the last item in the
806 list returned from the subroutine, I<Adder> actually made it back to
807 I<call_AddSubScalar>.
810 =head2 Returning Data from Perl via the parameter list
812 It is also possible to return values directly via the parameter list -
813 whether it is actually desirable to do it is another matter entirely.
815 The Perl subroutine, I<Inc>, below takes 2 parameters and increments
824 and here is a C function to call it.
839 sva = sv_2mortal(newSViv(a)) ;
840 svb = sv_2mortal(newSViv(b)) ;
847 count = perl_call_pv("Inc", G_DISCARD);
850 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
853 printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
854 printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
860 To be able to access the two parameters that were pushed onto the stack
861 after they return from I<perl_call_pv> it is necessary to make a note
862 of their addresses - thus the two variables C<sva> and C<svb>.
864 The reason this is necessary is that the area of the Perl stack which
865 held them will very likely have been overwritten by something else by
866 the time control returns from I<perl_call_pv>.
873 Now an example using G_EVAL. Below is a Perl subroutine which computes
874 the difference of its 2 parameters. If this would result in a negative
875 result, the subroutine calls I<die>.
881 die "death can be fatal\n" if $a < $b ;
886 and some C to call it
901 XPUSHs(sv_2mortal(newSViv(a)));
902 XPUSHs(sv_2mortal(newSViv(b)));
905 count = perl_call_pv("Subtract", G_EVAL|G_SCALAR);
909 /* Check the eval first */
910 sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
913 printf ("Uh oh - %s\n", SvPV(sv, na)) ;
919 croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
922 printf ("%d - %d = %d\n", a, b, POPi) ;
930 If I<call_Subtract> is called thus
934 the following will be printed
936 Uh oh - death can be fatal
944 We want to be able to catch the I<die> so we have used the G_EVAL
945 flag. Not specifying this flag would mean that the program would
946 terminate immediately at the I<die> statement in the subroutine
953 sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
956 printf ("Uh oh - %s\n", SvPVx(sv, na)) ;
960 is the direct equivalent of this bit of Perl
962 print "Uh oh - $@\n" if $@ ;
966 Note that the stack is popped using C<POPs> in the block where
967 C<SvTRUE(sv)> is true. This is necessary because whenever a
968 I<perl_call_*> function invoked with G_EVAL|G_SCALAR returns an error,
969 the top of the stack holds the value I<undef>. Since we want the
970 program to continue after detecting this error, it is essential that
971 the stack is tidied up by removing the I<undef>.
976 =head2 Using perl_call_sv
978 In all the previous examples I have 'hard-wired' the name of the Perl
979 subroutine to be called from C. Most of the time though, it is more
980 convenient to be able to specify the name of the Perl subroutine from
981 within the Perl script.
983 Consider the Perl code below
987 print "Hello there\n" ;
992 Here is a snippet of XSUB which defines I<CallSubPV>.
999 perl_call_pv(name, G_DISCARD|G_NOARGS) ;
1001 That is fine as far as it goes. The thing is, the Perl subroutine
1002 can be specified only as a string. For Perl 4 this was adequate,
1003 but Perl 5 allows references to subroutines and anonymous subroutines.
1004 This is where I<perl_call_sv> is useful.
1006 The code below for I<CallSubSV> is identical to I<CallSubPV> except
1007 that the C<name> parameter is now defined as an SV* and we use
1008 I<perl_call_sv> instead of I<perl_call_pv>.
1015 perl_call_sv(name, G_DISCARD|G_NOARGS) ;
1017 Since we are using an SV to call I<fred> the following can all be used
1023 CallSubSV( sub { print "Hello there\n" } ) ;
1025 As you can see, I<perl_call_sv> gives you much greater flexibility in
1026 how you can specify the Perl subroutine.
1028 You should note that if it is necessary to store the SV (C<name> in the
1029 example above) which corresponds to the Perl subroutine so that it can
1030 be used later in the program, it not enough to just store a copy of the
1031 pointer to the SV. Say the code above had been like this
1033 static SV * rememberSub ;
1039 rememberSub = name ;
1045 perl_call_sv(rememberSub, G_DISCARD|G_NOARGS) ;
1047 The reason this is wrong is that by the time you come to use the
1048 pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1049 to the Perl subroutine that was recorded in C<SaveSub1>. This is
1050 particularly true for these cases
1055 SaveSub1( sub { print "Hello there\n" } ) ;
1058 By the time each of the C<SaveSub1> statements above have been executed,
1059 the SV*'s which corresponded to the parameters will no longer exist.
1060 Expect an error message from Perl of the form
1062 Can't use an undefined value as a subroutine reference at ...
1064 for each of the C<CallSavedSub1> lines.
1066 Similarly, with this code
1073 you can expect one of these messages (which you actually get is dependant on
1074 the version of Perl you are using)
1076 Not a CODE reference at ...
1077 Undefined subroutine &main::47 called ...
1079 The variable C<$ref> may have referred to the subroutine C<fred>
1080 whenever the call to C<SaveSub1> was made but by the time
1081 C<CallSavedSub1> gets called it now holds the number C<47>. Since we
1082 saved only a pointer to the original SV in C<SaveSub1>, any changes to
1083 C<$ref> will be tracked by the pointer C<rememberSub>. This means that
1084 whenever C<CallSavedSub1> gets called, it will attempt to execute the
1085 code which is referenced by the SV* C<rememberSub>. In this case
1086 though, it now refers to the integer C<47>, so expect Perl to complain
1089 A similar but more subtle problem is illustrated with this code
1096 This time whenever C<CallSavedSub1> get called it will execute the Perl
1097 subroutine C<joe> (assuming it exists) rather than C<fred> as was
1098 originally requested in the call to C<SaveSub1>.
1100 To get around these problems it is necessary to take a full copy of the
1101 SV. The code below shows C<SaveSub2> modified to do that
1103 static SV * keepSub = (SV*)NULL ;
1109 /* Take a copy of the callback */
1110 if (keepSub == (SV*)NULL)
1111 /* First time, so create a new SV */
1112 keepSub = newSVsv(name) ;
1114 /* Been here before, so overwrite */
1115 SvSetSV(keepSub, name) ;
1121 perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ;
1123 In order to avoid creating a new SV every time C<SaveSub2> is called,
1124 the function first checks to see if it has been called before. If not,
1125 then space for a new SV is allocated and the reference to the Perl
1126 subroutine, C<name> is copied to the variable C<keepSub> in one
1127 operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called
1128 the existing SV, C<keepSub>, is overwritten with the new value using
1131 =head2 Using perl_call_argv
1133 Here is a Perl subroutine which prints whatever parameters are passed
1140 foreach (@list) { print "$_\n" }
1143 and here is an example of I<perl_call_argv> which will call
1146 static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ;
1153 perl_call_argv("PrintList", G_DISCARD, words) ;
1156 Note that it is not necessary to call C<PUSHMARK> in this instance.
1157 This is because I<perl_call_argv> will do it for you.
1159 =head2 Using perl_call_method
1161 Consider the following Perl code
1174 my ($self, $index) = @_ ;
1175 print "$index: $$self[$index]\n" ;
1181 print "This is Class $class version 1.0\n" ;
1185 It just implements a very simple class to manage an array. Apart from
1186 the constructor, C<new>, it declares methods, one static and one
1187 virtual. The static method, C<PrintID>, simply prints out the class
1188 name and a version number. The virtual method, C<Display>, prints out a
1189 single element of the array. Here is an all Perl example of using it.
1191 $a = new Mine ('red', 'green', 'blue') ;
1198 This is Class Mine version 1.0
1200 Calling a Perl method from C is fairly straightforward. The following
1207 a reference to the object for a virtual method or the name of the class
1208 for a static method.
1212 the name of the method.
1216 any other parameters specific to the method.
1220 Here is a simple XSUB which illustrates the mechanics of calling both
1221 the C<PrintID> and C<Display> methods from C.
1224 call_Method(ref, method, index)
1231 XPUSHs(sv_2mortal(newSViv(index))) ;
1234 perl_call_method(method, G_DISCARD) ;
1237 call_PrintID(class, method)
1242 XPUSHs(sv_2mortal(newSVpv(class, 0))) ;
1245 perl_call_method(method, G_DISCARD) ;
1248 So the methods C<PrintID> and C<Display> can be invoked like this
1250 $a = new Mine ('red', 'green', 'blue') ;
1251 call_Method($a, 'Display', 1) ;
1252 call_PrintID('Mine', 'PrintID') ;
1254 The only thing to note is that in both the static and virtual methods,
1255 the method name is not passed via the stack - it is used as the first
1256 parameter to I<perl_call_method>.
1260 Here is a trivial XSUB which prints the context in which it is
1261 currently executing.
1266 if (GIMME == G_SCALAR)
1267 printf ("Context is Scalar\n") ;
1269 printf ("Context is Array\n") ;
1271 and here is some Perl to test it
1276 The output from that will be
1281 =head2 Using Perl to dispose of temporaries
1283 In the examples given to date, any temporaries created in the callback
1284 (i.e. parameters passed on the stack to the I<perl_call_*> function or
1285 values returned via the stack) have been freed by one of these methods
1291 specifying the G_DISCARD flag with I<perl_call_*>.
1295 explicitly disposed of using the C<ENTER>/C<SAVETMPS> -
1296 C<FREETMPS>/C<LEAVE> pairing.
1300 There is another method which can be used, namely letting Perl do it
1301 for you automatically whenever it regains control after the callback
1302 has terminated. This is done by simply not using the
1310 sequence in the callback (and not, of course, specifying the G_DISCARD
1313 If you are going to use this method you have to be aware of a possible
1314 memory leak which can arise under very specific circumstances. To
1315 explain these circumstances you need to know a bit about the flow of
1316 control between Perl and the callback routine.
1318 The examples given at the start of the document (an error handler and
1319 an event driven program) are typical of the two main sorts of flow
1320 control that you are likely to encounter with callbacks. There is a
1321 very important distinction between them, so pay attention.
1323 In the first example, an error handler, the flow of control could be as
1324 follows. You have created an interface to an external library.
1325 Control can reach the external library like this
1327 perl --> XSUB --> external library
1329 Whilst control is in the library, an error condition occurs. You have
1330 previously set up a Perl callback to handle this situation, so it will
1331 get executed. Once the callback has finished, control will drop back to
1332 Perl again. Here is what the flow of control will be like in that
1335 perl --> XSUB --> external library
1339 external library --> perl_call --> perl
1341 perl <-- XSUB <-- external library <-- perl_call <----+
1343 After processing of the error using I<perl_call_*> is completed,
1344 control reverts back to Perl more or less immediately.
1346 In the diagram, the further right you go the more deeply nested the
1347 scope is. It is only when control is back with perl on the extreme
1348 left of the diagram that you will have dropped back to the enclosing
1349 scope and any temporaries you have left hanging around will be freed.
1351 In the second example, an event driven program, the flow of control
1352 will be more like this
1354 perl --> XSUB --> event handler
1356 event handler --> perl_call --> perl
1358 event handler <-- perl_call --<--+
1360 event handler --> perl_call --> perl
1362 event handler <-- perl_call --<--+
1364 event handler --> perl_call --> perl
1366 event handler <-- perl_call --<--+
1368 In this case the flow of control can consist of only the repeated
1371 event handler --> perl_call --> perl
1373 for the practically the complete duration of the program. This means
1374 that control may I<never> drop back to the surrounding scope in Perl at
1377 So what is the big problem? Well, if you are expecting Perl to tidy up
1378 those temporaries for you, you might be in for a long wait. For Perl
1379 to actually dispose of your temporaries, control must drop back to the
1380 enclosing scope at some stage. In the event driven scenario that may
1381 never happen. This means that as time goes on, your program will
1382 create more and more temporaries, none of which will ever be freed. As
1383 each of these temporaries consumes some memory your program will
1384 eventually consume all the available memory in your system - kapow!
1386 So here is the bottom line - if you are sure that control will revert
1387 back to the enclosing Perl scope fairly quickly after the end of your
1388 callback, then it isn't absolutely necessary to explicitly dispose of
1389 any temporaries you may have created. Mind you, if you are at all
1390 uncertain about what to do, it doesn't do any harm to tidy up anyway.
1393 =head2 Strategies for storing Callback Context Information
1396 Potentially one of the trickiest problems to overcome when designing a
1397 callback interface can be figuring out how to store the mapping between
1398 the C callback function and the Perl equivalent.
1400 To help understand why this can be a real problem first consider how a
1401 callback is set up in an all C environment. Typically a C API will
1402 provide a function to register a callback. This will expect a pointer
1403 to a function as one of its parameters. Below is a call to a
1404 hypothetical function C<register_fatal> which registers the C function
1405 to get called when a fatal error occurs.
1407 register_fatal(cb1) ;
1409 The single parameter C<cb1> is a pointer to a function, so you must
1410 have defined C<cb1> in your code, say something like this
1415 printf ("Fatal Error\n") ;
1419 Now change that to call a Perl subroutine instead
1421 static SV * callback = (SV*)NULL;
1430 /* Call the Perl sub to process the callback */
1431 perl_call_sv(callback, G_DISCARD) ;
1439 /* Remember the Perl sub */
1440 if (callback == (SV*)NULL)
1441 callback = newSVsv(fn) ;
1443 SvSetSV(callback, fn) ;
1445 /* register the callback with the external library */
1446 register_fatal(cb1) ;
1448 where the Perl equivalent of C<register_fatal> and the callback it
1449 registers, C<pcb1>, might look like this
1451 # Register the sub pcb1
1452 register_fatal(\&pcb1) ;
1456 die "I'm dying...\n" ;
1459 The mapping between the C callback and the Perl equivalent is stored in
1460 the global variable C<callback>.
1462 This will be adequate if you ever need to have only 1 callback
1463 registered at any time. An example could be an error handler like the
1464 code sketched out above. Remember though, repeated calls to
1465 C<register_fatal> will replace the previously registered callback
1466 function with the new one.
1468 Say for example you want to interface to a library which allows asynchronous
1469 file i/o. In this case you may be able to register a callback whenever
1470 a read operation has completed. To be of any use we want to be able to
1471 call separate Perl subroutines for each file that is opened. As it
1472 stands, the error handler example above would not be adequate as it
1473 allows only a single callback to be defined at any time. What we
1474 require is a means of storing the mapping between the opened file and
1475 the Perl subroutine we want to be called for that file.
1477 Say the i/o library has a function C<asynch_read> which associates a C
1478 function C<ProcessRead> with a file handle C<fh> - this assumes that it
1479 has also provided some routine to open the file and so obtain the file
1482 asynch_read(fh, ProcessRead)
1484 This may expect the C I<ProcessRead> function of this form
1487 ProcessRead(fh, buffer)
1494 To provide a Perl interface to this library we need to be able to map
1495 between the C<fh> parameter and the Perl subroutine we want called. A
1496 hash is a convenient mechanism for storing this mapping. The code
1497 below shows a possible implementation
1499 static HV * Mapping = (HV*)NULL ;
1502 asynch_read(fh, callback)
1506 /* If the hash doesn't already exist, create it */
1507 if (Mapping == (HV*)NULL)
1510 /* Save the fh -> callback mapping */
1511 hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ;
1513 /* Register with the C Library */
1514 asynch_read(fh, asynch_read_if) ;
1516 and C<asynch_read_if> could look like this
1519 asynch_read_if(fh, buffer)
1526 /* Get the callback associated with fh */
1527 sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE) ;
1528 if (sv == (SV**)NULL)
1529 croak("Internal error...\n") ;
1532 XPUSHs(sv_2mortal(newSViv(fh))) ;
1533 XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1536 /* Call the Perl sub */
1537 perl_call_sv(*sv, G_DISCARD) ;
1540 For completeness, here is C<asynch_close>. This shows how to remove
1541 the entry from the hash C<Mapping>.
1547 /* Remove the entry from the hash */
1548 (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ;
1550 /* Now call the real asynch_close */
1553 So the Perl interface would look like this
1557 my($handle, $buffer) = @_ ;
1560 # Register the Perl callback
1561 asynch_read($fh, \&callback1) ;
1565 The mapping between the C callback and Perl is stored in the global
1566 hash C<Mapping> this time. Using a hash has the distinct advantage that
1567 it allows an unlimited number of callbacks to be registered.
1569 What if the interface provided by the C callback doesn't contain a
1570 parameter which allows the file handle to Perl subroutine mapping? Say
1571 in the asynchronous i/o package, the callback function gets passed only
1572 the C<buffer> parameter like this
1581 Without the file handle there is no straightforward way to map from the
1582 C callback to the Perl subroutine.
1584 In this case a possible way around this problem is to pre-define a
1585 series of C functions to act as the interface to Perl, thus
1588 #define NULL_HANDLE -1
1589 typedef void (*FnMap)() ;
1601 static struct MapStruct Map [MAX_CB] =
1603 { fn1, NULL, NULL_HANDLE },
1604 { fn2, NULL, NULL_HANDLE },
1605 { fn3, NULL, NULL_HANDLE }
1616 XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1619 /* Call the Perl sub */
1620 perl_call_sv(Map[index].PerlSub, G_DISCARD) ;
1645 array_asynch_read(fh, callback)
1650 int null_index = MAX_CB ;
1652 /* Find the same handle or an empty entry */
1653 for (index = 0 ; index < MAX_CB ; ++index)
1655 if (Map[index].Handle == fh)
1658 if (Map[index].Handle == NULL_HANDLE)
1659 null_index = index ;
1662 if (index == MAX_CB && null_index == MAX_CB)
1663 croak ("Too many callback functions registered\n") ;
1665 if (index == MAX_CB)
1666 index = null_index ;
1668 /* Save the file handle */
1669 Map[index].Handle = fh ;
1671 /* Remember the Perl sub */
1672 if (Map[index].PerlSub == (SV*)NULL)
1673 Map[index].PerlSub = newSVsv(callback) ;
1675 SvSetSV(Map[index].PerlSub, callback) ;
1677 asynch_read(fh, Map[index].Function) ;
1680 array_asynch_close(fh)
1685 /* Find the file handle */
1686 for (index = 0; index < MAX_CB ; ++ index)
1687 if (Map[index].Handle == fh)
1690 if (index == MAX_CB)
1691 croak ("could not close fh %d\n", fh) ;
1693 Map[index].Handle = NULL_HANDLE ;
1694 SvREFCNT_dec(Map[index].PerlSub) ;
1695 Map[index].PerlSub = (SV*)NULL ;
1699 In this case the functions C<fn1>, C<fn2> and C<fn3> are used to
1700 remember the Perl subroutine to be called. Each of the functions holds
1701 a separate hard-wired index which is used in the function C<Pcb> to
1702 access the C<Map> array and actually call the Perl subroutine.
1704 There are some obvious disadvantages with this technique.
1706 Firstly, the code is considerably more complex than with the previous
1709 Secondly, there is a hard-wired limit (in this case 3) to the number of
1710 callbacks that can exist simultaneously. The only way to increase the
1711 limit is by modifying the code to add more functions and then
1712 re-compiling. None the less, as long as the number of functions is
1713 chosen with some care, it is still a workable solution and in some
1714 cases is the only one available.
1716 To summarize, here are a number of possible methods for you to consider
1717 for storing the mapping between C and the Perl callback
1721 =item 1. Ignore the problem - Allow only 1 callback
1723 For a lot of situations, like interfacing to an error handler, this may
1724 be a perfectly adequate solution.
1726 =item 2. Create a sequence of callbacks - hard wired limit
1728 If it is impossible to tell from the parameters passed back from the C
1729 callback what the context is, then you may need to create a sequence of C
1730 callback interface functions, and store pointers to each in an array.
1732 =item 3. Use a parameter to map to the Perl callback
1734 A hash is an ideal mechanism to store the mapping between C and Perl.
1739 =head2 Alternate Stack Manipulation
1742 Although I have made use of only the C<POP*> macros to access values
1743 returned from Perl subroutines, it is also possible to bypass these
1744 macros and read the stack using the C<ST> macro (See L<perlapi> for a
1745 full description of the C<ST> macro).
1747 Most of the time the C<POP*> macros should be adequate, the main
1748 problem with them is that they force you to process the returned values
1749 in sequence. This may not be the most suitable way to process the
1750 values in some cases. What we want is to be able to access the stack in
1751 a random order. The C<ST> macro as used when coding an XSUB is ideal
1754 The code below is the example given in the section I<Returning a list
1755 of values> recoded to use C<ST> instead of C<POP*>.
1758 call_AddSubtract2(a, b)
1770 XPUSHs(sv_2mortal(newSViv(a)));
1771 XPUSHs(sv_2mortal(newSViv(b)));
1774 count = perl_call_pv("AddSubtract", G_ARRAY);
1778 ax = (sp - stack_base) + 1 ;
1781 croak("Big trouble\n") ;
1783 printf ("%d + %d = %d\n", a, b, SvIV(ST(0))) ;
1784 printf ("%d - %d = %d\n", a, b, SvIV(ST(1))) ;
1797 Notice that it was necessary to define the variable C<ax>. This is
1798 because the C<ST> macro expects it to exist. If we were in an XSUB it
1799 would not be necessary to define C<ax> as it is already defined for
1808 ax = (sp - stack_base) + 1 ;
1810 sets the stack up so that we can use the C<ST> macro.
1814 Unlike the original coding of this example, the returned
1815 values are not accessed in reverse order. So C<ST(0)> refers to the
1816 first value returned by the Perl subroutine and C<ST(count-1)>
1823 L<perlapi>, L<perlguts>, L<perlembed>
1827 Paul Marquess <pmarquess@bfsec.bt.co.uk>
1829 Special thanks to the following people who assisted in the creation of
1832 Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem and Larry Wall.
1836 Version 1.1, 17th May 1995