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 you 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<perlxs> and L<perlguts>.
48 =head1 THE 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 call_sv(SV* sv, I32 flags) ;
57 I32 call_pv(char *subname, I32 flags) ;
58 I32 call_method(char *methname, I32 flags) ;
59 I32 call_argv(char *subname, I32 flags, register char **argv) ;
61 The key function is I<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<call_sv>
64 to invoke the Perl subroutine.
66 All the I<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<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 call_sv>, shows how you can make
85 The function, I<call_pv>, is similar to I<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<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">.
93 The function I<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 call_method> for an example
100 of using I<call_method>.
104 I<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 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<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 void context.
133 This flag has 2 effects:
139 It indicates to the subroutine being called that it is executing in
140 a void context (if it executes I<wantarray> the result will be the
145 It ensures that nothing is actually returned from the subroutine.
149 The value returned by the I<call_*> function indicates how many
150 items have been returned by the Perl subroutine - in this case it will
156 Calls the Perl subroutine in a scalar context. This is the default
157 context flag setting for all the I<call_*> functions.
159 This flag has 2 effects:
165 It indicates to the subroutine being called that it is executing in a
166 scalar context (if it executes I<wantarray> the result will be false).
170 It ensures that only a scalar is actually returned from the subroutine.
171 The subroutine can, of course, ignore the I<wantarray> and return a
172 list anyway. If so, then only the last element of the list will be
177 The value returned by the I<call_*> function indicates how many
178 items have been returned by the Perl subroutine - in this case it will
181 If 0, then you have specified the G_DISCARD flag.
183 If 1, then the item actually returned by the Perl subroutine will be
184 stored on the Perl stack - the section I<Returning a Scalar> shows how
185 to access this value on the stack. Remember that regardless of how
186 many items the Perl subroutine returns, only the last one will be
187 accessible from the stack - think of the case where only one value is
188 returned as being a list with only one element. Any other items that
189 were returned will not exist by the time control returns from the
190 I<call_*> function. The section I<Returning a list in a scalar
191 context> shows an example of this behavior.
196 Calls the Perl subroutine in a list context.
198 As with G_SCALAR, this flag has 2 effects:
204 It indicates to the subroutine being called that it is executing in a
205 list context (if it executes I<wantarray> the result will be true).
210 It ensures that all items returned from the subroutine will be
211 accessible when control returns from the I<call_*> function.
215 The value returned by the I<call_*> function indicates how many
216 items have been returned by the Perl subroutine.
218 If 0, then you have specified the G_DISCARD flag.
220 If not 0, then it will be a count of the number of items returned by
221 the subroutine. These items will be stored on the Perl stack. The
222 section I<Returning a list of values> gives an example of using the
223 G_ARRAY flag and the mechanics of accessing the returned items from the
228 By default, the I<call_*> functions place the items returned from
229 by the Perl subroutine on the stack. If you are not interested in
230 these items, then setting this flag will make Perl get rid of them
231 automatically for you. Note that it is still possible to indicate a
232 context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
234 If you do not set this flag then it is I<very> important that you make
235 sure that any temporaries (i.e., parameters passed to the Perl
236 subroutine and values returned from the subroutine) are disposed of
237 yourself. The section I<Returning a Scalar> gives details of how to
238 dispose of these temporaries explicitly and the section I<Using Perl to
239 dispose of temporaries> discusses the specific circumstances where you
240 can ignore the problem and let Perl deal with it for you.
244 Whenever a Perl subroutine is called using one of the I<call_*>
245 functions, it is assumed by default that parameters are to be passed to
246 the subroutine. If you are not passing any parameters to the Perl
247 subroutine, you can save a bit of time by setting this flag. It has
248 the effect of not creating the C<@_> array for the Perl subroutine.
250 Although the functionality provided by this flag may seem
251 straightforward, it should be used only if there is a good reason to do
252 so. The reason for being cautious is that even if you have specified
253 the G_NOARGS flag, it is still possible for the Perl subroutine that
254 has been called to think that you have passed it parameters.
256 In fact, what can happen is that the Perl subroutine you have called
257 can access the C<@_> array from a previous Perl subroutine. This will
258 occur when the code that is executing the I<call_*> function has
259 itself been called from another Perl subroutine. The code below
276 What has happened is that C<fred> accesses the C<@_> array which
282 It is possible for the Perl subroutine you are calling to terminate
283 abnormally, e.g., by calling I<die> explicitly or by not actually
284 existing. By default, when either of these events occurs, the
285 process will terminate immediately. If you want to trap this
286 type of event, specify the G_EVAL flag. It will put an I<eval { }>
287 around the subroutine call.
289 Whenever control returns from the I<call_*> function you need to
290 check the C<$@> variable as you would in a normal Perl script.
292 The value returned from the I<call_*> function is dependent on
293 what other flags have been specified and whether an error has
294 occurred. Here are all the different cases that can occur:
300 If the I<call_*> function returns normally, then the value
301 returned is as specified in the previous sections.
305 If G_DISCARD is specified, the return value will always be 0.
309 If G_ARRAY is specified I<and> an error has occurred, the return value
314 If G_SCALAR is specified I<and> an error has occurred, the return value
315 will be 1 and the value on the top of the stack will be I<undef>. This
316 means that if you have already detected the error by checking C<$@> and
317 you want the program to continue, you must remember to pop the I<undef>
322 See I<Using G_EVAL> for details on using G_EVAL.
326 You may have noticed that using the G_EVAL flag described above will
327 B<always> clear the C<$@> variable and set it to a string describing
328 the error iff there was an error in the called code. This unqualified
329 resetting of C<$@> can be problematic in the reliable identification of
330 errors using the C<eval {}> mechanism, because the possibility exists
331 that perl will call other code (end of block processing code, for
332 example) between the time the error causes C<$@> to be set within
333 C<eval {}>, and the subsequent statement which checks for the value of
334 C<$@> gets executed in the user's script.
336 This scenario will mostly be applicable to code that is meant to be
337 called from within destructors, asynchronous callbacks, signal
338 handlers, C<__DIE__> or C<__WARN__> hooks, and C<tie> functions. In
339 such situations, you will not want to clear C<$@> at all, but simply to
340 append any new errors to any existing value of C<$@>.
342 The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
343 I<call_*> functions that are used to implement such code. This flag
344 has no effect when G_EVAL is not used.
346 When G_KEEPERR is used, any errors in the called code will be prefixed
347 with the string "\t(in cleanup)", and appended to the current value
350 The G_KEEPERR flag was introduced in Perl version 5.002.
352 See I<Using G_KEEPERR> for an example of a situation that warrants the
355 =head2 Determining the Context
357 As mentioned above, you can determine the context of the currently
358 executing subroutine in Perl with I<wantarray>. The equivalent test
359 can be made in C by using the C<GIMME_V> macro, which returns
360 C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
361 in a scalar context, or C<G_VOID> if in a void context (i.e. the
362 return value will not be used). An older version of this macro is
363 called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
364 C<G_VOID>. An example of using the C<GIMME_V> macro is shown in
365 section I<Using GIMME_V>.
367 =head1 KNOWN PROBLEMS
369 This section outlines all known problems that exist in the
376 If you are intending to make use of both the G_EVAL and G_SCALAR flags
377 in your code, use a version of Perl greater than 5.000. There is a bug
378 in version 5.000 of Perl which means that the combination of these two
379 flags will not work as described in the section I<FLAG VALUES>.
381 Specifically, if the two flags are used when calling a subroutine and
382 that subroutine does not call I<die>, the value returned by
383 I<call_*> will be wrong.
388 In Perl 5.000 and 5.001 there is a problem with using I<call_*> if
389 the Perl sub you are calling attempts to trap a I<die>.
391 The symptom of this problem is that the called Perl sub will continue
392 to completion, but whenever it attempts to pass control back to the
393 XSUB, the program will immediately terminate.
395 For example, say you want to call this Perl sub
398 eval { die "Fatal Error" }
399 print "Trapped error: $@\n" if $@;
408 call_pv("fred", G_DISCARD|G_NOARGS) ;
409 fprintf(stderr, "back in Call_fred\n") ;
411 When C<Call_fred> is executed it will print
413 Trapped error: Fatal Error
415 As control never returns to C<Call_fred>, the C<"back in Call_fred">
416 string will not get printed.
418 To work around this problem, you can either upgrade to Perl 5.002 or
419 higher, or use the G_EVAL flag with I<call_*> as shown below
425 call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ;
426 fprintf(stderr, "back in Call_fred\n") ;
434 Enough of the definition talk, let's have a few examples.
436 Perl provides many macros to assist in accessing the Perl stack.
437 Wherever possible, these macros should always be used when interfacing
438 to Perl internals. We hope this should make the code less vulnerable
439 to any changes made to Perl in the future.
441 Another point worth noting is that in the first series of examples I
442 have made use of only the I<call_pv> function. This has been done
443 to keep the code simpler and ease you into the topic. Wherever
444 possible, if the choice is between using I<call_pv> and
445 I<call_sv>, you should always try to use I<call_sv>. See
446 I<Using call_sv> for details.
448 =head2 No Parameters, Nothing returned
450 This first trivial example will call a Perl subroutine, I<PrintUID>, to
451 print out the UID of the process.
457 and here is a C function to call it
465 call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
470 A few points to note about this example.
476 Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
481 We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
486 We aren't interested in anything returned from I<PrintUID>, so
487 G_DISCARD is specified. Even if I<PrintUID> was changed to
488 return some value(s), having specified G_DISCARD will mean that they
489 will be wiped by the time control returns from I<call_pv>.
493 As I<call_pv> is being used, the Perl subroutine is specified as a
494 C string. In this case the subroutine name has been 'hard-wired' into the
499 Because we specified G_DISCARD, it is not necessary to check the value
500 returned from I<call_pv>. It will always be 0.
504 =head2 Passing Parameters
506 Now let's make a slightly more complex example. This time we want to
507 call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
508 string ($s) and an integer ($n). The subroutine will simply
509 print the first $n characters of the string.
511 So the Perl subroutine would look like this
515 print substr($s, 0, $n), "\n";
518 The C function required to call I<LeftString> would look like this.
521 call_LeftString(a, b)
531 XPUSHs(sv_2mortal(newSVpv(a, 0)));
532 XPUSHs(sv_2mortal(newSViv(b)));
535 call_pv("LeftString", G_DISCARD);
541 Here are a few notes on the C function I<call_LeftString>.
547 Parameters are passed to the Perl subroutine using the Perl stack.
548 This is the purpose of the code beginning with the line C<dSP> and
549 ending with the line C<PUTBACK>. The C<dSP> declares a local copy
550 of the stack pointer. This local copy should B<always> be accessed
555 If you are going to put something onto the Perl stack, you need to know
556 where to put it. This is the purpose of the macro C<dSP>--it declares
557 and initializes a I<local> copy of the Perl stack pointer.
559 All the other macros which will be used in this example require you to
560 have used this macro.
562 The exception to this rule is if you are calling a Perl subroutine
563 directly from an XSUB function. In this case it is not necessary to
564 use the C<dSP> macro explicitly--it will be declared for you
569 Any parameters to be pushed onto the stack should be bracketed by the
570 C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
571 this context, is to count the number of parameters you are
572 pushing automatically. Then whenever Perl is creating the C<@_> array for the
573 subroutine, it knows how big to make it.
575 The C<PUSHMARK> macro tells Perl to make a mental note of the current
576 stack pointer. Even if you aren't passing any parameters (like the
577 example shown in the section I<No Parameters, Nothing returned>) you
578 must still call the C<PUSHMARK> macro before you can call any of the
579 I<call_*> functions--Perl still needs to know that there are no
582 The C<PUTBACK> macro sets the global copy of the stack pointer to be
583 the same as our local copy. If we didn't do this I<call_pv>
584 wouldn't know where the two parameters we pushed were--remember that
585 up to now all the stack pointer manipulation we have done is with our
586 local copy, I<not> the global copy.
590 Next, we come to XPUSHs. This is where the parameters actually get
591 pushed onto the stack. In this case we are pushing a string and an
594 See L<perlguts/"XSUBs and the Argument Stack"> for details
595 on how the XPUSH macros work.
599 Because we created temporary values (by means of sv_2mortal() calls)
600 we will have to tidy up the Perl stack and dispose of mortal SVs.
602 This is the purpose of
607 at the start of the function, and
612 at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
613 temporaries we create. This means that the temporaries we get rid of
614 will be limited to those which were created after these calls.
616 The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
617 the Perl subroutine (see next example), plus it will also dump the
618 mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the
619 beginning of the code makes sure that no other mortals are destroyed.
621 Think of these macros as working a bit like using C<{> and C<}> in Perl
622 to limit the scope of local variables.
624 See the section I<Using Perl to dispose of temporaries> for details of
625 an alternative to using these macros.
629 Finally, I<LeftString> can now be called via the I<call_pv> function.
630 The only flag specified this time is G_DISCARD. Because we are passing
631 2 parameters to the Perl subroutine this time, we have not specified
636 =head2 Returning a Scalar
638 Now for an example of dealing with the items returned from a Perl
641 Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
642 and simply returns their sum.
649 Because we are now concerned with the return value from I<Adder>, the C
650 function required to call it is now a bit more complex.
664 XPUSHs(sv_2mortal(newSViv(a)));
665 XPUSHs(sv_2mortal(newSViv(b)));
668 count = call_pv("Adder", G_SCALAR);
673 croak("Big trouble\n") ;
675 printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
682 Points to note this time are
688 The only flag specified this time was G_SCALAR. That means the C<@_>
689 array will be created and that the value returned by I<Adder> will
690 still exist after the call to I<call_pv>.
694 The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
695 stack pointer. This is necessary because it is possible that the memory
696 allocated to the Perl stack has been reallocated whilst in the
699 If you are making use of the Perl stack pointer in your code you must
700 always refresh the local copy using SPAGAIN whenever you make use
701 of the I<call_*> functions or any other Perl internal function.
705 Although only a single value was expected to be returned from I<Adder>,
706 it is still good practice to check the return code from I<call_pv>
709 Expecting a single value is not quite the same as knowing that there
710 will be one. If someone modified I<Adder> to return a list and we
711 didn't check for that possibility and take appropriate action the Perl
712 stack would end up in an inconsistent state. That is something you
713 I<really> don't want to happen ever.
717 The C<POPi> macro is used here to pop the return value from the stack.
718 In this case we wanted an integer, so C<POPi> was used.
721 Here is the complete list of POP macros available, along with the types
732 The final C<PUTBACK> is used to leave the Perl stack in a consistent
733 state before exiting the function. This is necessary because when we
734 popped the return value from the stack with C<POPi> it updated only our
735 local copy of the stack pointer. Remember, C<PUTBACK> sets the global
736 stack pointer to be the same as our local copy.
741 =head2 Returning a list of values
743 Now, let's extend the previous example to return both the sum of the
744 parameters and the difference.
746 Here is the Perl subroutine
753 and this is the C function
756 call_AddSubtract(a, b)
767 XPUSHs(sv_2mortal(newSViv(a)));
768 XPUSHs(sv_2mortal(newSViv(b)));
771 count = call_pv("AddSubtract", G_ARRAY);
776 croak("Big trouble\n") ;
778 printf ("%d - %d = %d\n", a, b, POPi) ;
779 printf ("%d + %d = %d\n", a, b, POPi) ;
786 If I<call_AddSubtract> is called like this
788 call_AddSubtract(7, 4) ;
790 then here is the output
801 We wanted list context, so G_ARRAY was used.
805 Not surprisingly C<POPi> is used twice this time because we were
806 retrieving 2 values from the stack. The important thing to note is that
807 when using the C<POP*> macros they come off the stack in I<reverse>
812 =head2 Returning a list in a scalar context
814 Say the Perl subroutine in the previous section was called in a scalar
818 call_AddSubScalar(a, b)
830 XPUSHs(sv_2mortal(newSViv(a)));
831 XPUSHs(sv_2mortal(newSViv(b)));
834 count = call_pv("AddSubtract", G_SCALAR);
838 printf ("Items Returned = %d\n", count) ;
840 for (i = 1 ; i <= count ; ++i)
841 printf ("Value %d = %d\n", i, POPi) ;
848 The other modification made is that I<call_AddSubScalar> will print the
849 number of items returned from the Perl subroutine and their value (for
850 simplicity it assumes that they are integer). So if
851 I<call_AddSubScalar> is called
853 call_AddSubScalar(7, 4) ;
855 then the output will be
860 In this case the main point to note is that only the last item in the
861 list is returned from the subroutine, I<AddSubtract> actually made it back to
862 I<call_AddSubScalar>.
865 =head2 Returning Data from Perl via the parameter list
867 It is also possible to return values directly via the parameter list -
868 whether it is actually desirable to do it is another matter entirely.
870 The Perl subroutine, I<Inc>, below takes 2 parameters and increments
878 and here is a C function to call it.
893 sva = sv_2mortal(newSViv(a)) ;
894 svb = sv_2mortal(newSViv(b)) ;
901 count = call_pv("Inc", G_DISCARD);
904 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
907 printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
908 printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
914 To be able to access the two parameters that were pushed onto the stack
915 after they return from I<call_pv> it is necessary to make a note
916 of their addresses--thus the two variables C<sva> and C<svb>.
918 The reason this is necessary is that the area of the Perl stack which
919 held them will very likely have been overwritten by something else by
920 the time control returns from I<call_pv>.
927 Now an example using G_EVAL. Below is a Perl subroutine which computes
928 the difference of its 2 parameters. If this would result in a negative
929 result, the subroutine calls I<die>.
934 die "death can be fatal\n" if $a < $b;
939 and some C to call it
953 XPUSHs(sv_2mortal(newSViv(a)));
954 XPUSHs(sv_2mortal(newSViv(b)));
957 count = call_pv("Subtract", G_EVAL|G_SCALAR);
961 /* Check the eval first */
965 printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
971 croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
974 printf ("%d - %d = %d\n", a, b, POPi) ;
982 If I<call_Subtract> is called thus
986 the following will be printed
988 Uh oh - death can be fatal
996 We want to be able to catch the I<die> so we have used the G_EVAL
997 flag. Not specifying this flag would mean that the program would
998 terminate immediately at the I<die> statement in the subroutine
1008 printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
1012 is the direct equivalent of this bit of Perl
1014 print "Uh oh - $@\n" if $@ ;
1016 C<PL_errgv> is a perl global of type C<GV *> that points to the
1017 symbol table entry containing the error. C<ERRSV> therefore
1018 refers to the C equivalent of C<$@>.
1022 Note that the stack is popped using C<POPs> in the block where
1023 C<SvTRUE(ERRSV)> is true. This is necessary because whenever a
1024 I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
1025 the top of the stack holds the value I<undef>. Because we want the
1026 program to continue after detecting this error, it is essential that
1027 the stack is tidied up by removing the I<undef>.
1032 =head2 Using G_KEEPERR
1034 Consider this rather facetious example, where we have used an XS
1035 version of the call_Subtract example above inside a destructor:
1039 sub new { bless {}, shift }
1043 die "death can be fatal" if $a < $b;
1047 sub DESTROY { call_Subtract(5, 4) }
1048 sub foo { die "foo dies" }
1053 eval { Foo->new->foo };
1054 print "Saw: $@" if $@; # should be, but isn't
1056 This example will fail to recognize that an error occurred inside the
1057 C<eval {}>. Here's why: the call_Subtract code got executed while perl
1058 was cleaning up temporaries when exiting the eval block, and because
1059 call_Subtract is implemented with I<call_pv> using the G_EVAL
1060 flag, it promptly reset C<$@>. This results in the failure of the
1061 outermost test for C<$@>, and thereby the failure of the error trap.
1063 Appending the G_KEEPERR flag, so that the I<call_pv> call in
1064 call_Subtract reads:
1066 count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
1068 will preserve the error and restore reliable error handling.
1070 =head2 Using call_sv
1072 In all the previous examples I have 'hard-wired' the name of the Perl
1073 subroutine to be called from C. Most of the time though, it is more
1074 convenient to be able to specify the name of the Perl subroutine from
1075 within the Perl script.
1077 Consider the Perl code below
1080 print "Hello there\n";
1085 Here is a snippet of XSUB which defines I<CallSubPV>.
1092 call_pv(name, G_DISCARD|G_NOARGS) ;
1094 That is fine as far as it goes. The thing is, the Perl subroutine
1095 can be specified as only a string. For Perl 4 this was adequate,
1096 but Perl 5 allows references to subroutines and anonymous subroutines.
1097 This is where I<call_sv> is useful.
1099 The code below for I<CallSubSV> is identical to I<CallSubPV> except
1100 that the C<name> parameter is now defined as an SV* and we use
1101 I<call_sv> instead of I<call_pv>.
1108 call_sv(name, G_DISCARD|G_NOARGS) ;
1110 Because we are using an SV to call I<fred> the following can all be used
1117 CallSubSV( sub { print "Hello there\n" } );
1119 As you can see, I<call_sv> gives you much greater flexibility in
1120 how you can specify the Perl subroutine.
1122 You should note that if it is necessary to store the SV (C<name> in the
1123 example above) which corresponds to the Perl subroutine so that it can
1124 be used later in the program, it not enough just to store a copy of the
1125 pointer to the SV. Say the code above had been like this
1127 static SV * rememberSub ;
1133 rememberSub = name ;
1139 call_sv(rememberSub, G_DISCARD|G_NOARGS) ;
1141 The reason this is wrong is that by the time you come to use the
1142 pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1143 to the Perl subroutine that was recorded in C<SaveSub1>. This is
1144 particularly true for these cases
1149 SaveSub1( sub { print "Hello there\n" } );
1152 By the time each of the C<SaveSub1> statements above have been executed,
1153 the SV*s which corresponded to the parameters will no longer exist.
1154 Expect an error message from Perl of the form
1156 Can't use an undefined value as a subroutine reference at ...
1158 for each of the C<CallSavedSub1> lines.
1160 Similarly, with this code
1168 you can expect one of these messages (which you actually get is dependent on
1169 the version of Perl you are using)
1171 Not a CODE reference at ...
1172 Undefined subroutine &main::47 called ...
1174 The variable $ref may have referred to the subroutine C<fred>
1175 whenever the call to C<SaveSub1> was made but by the time
1176 C<CallSavedSub1> gets called it now holds the number C<47>. Because we
1177 saved only a pointer to the original SV in C<SaveSub1>, any changes to
1178 $ref will be tracked by the pointer C<rememberSub>. This means that
1179 whenever C<CallSavedSub1> gets called, it will attempt to execute the
1180 code which is referenced by the SV* C<rememberSub>. In this case
1181 though, it now refers to the integer C<47>, so expect Perl to complain
1184 A similar but more subtle problem is illustrated with this code
1192 This time whenever C<CallSavedSub1> get called it will execute the Perl
1193 subroutine C<joe> (assuming it exists) rather than C<fred> as was
1194 originally requested in the call to C<SaveSub1>.
1196 To get around these problems it is necessary to take a full copy of the
1197 SV. The code below shows C<SaveSub2> modified to do that
1199 static SV * keepSub = (SV*)NULL ;
1205 /* Take a copy of the callback */
1206 if (keepSub == (SV*)NULL)
1207 /* First time, so create a new SV */
1208 keepSub = newSVsv(name) ;
1210 /* Been here before, so overwrite */
1211 SvSetSV(keepSub, name) ;
1217 call_sv(keepSub, G_DISCARD|G_NOARGS) ;
1219 To avoid creating a new SV every time C<SaveSub2> is called,
1220 the function first checks to see if it has been called before. If not,
1221 then space for a new SV is allocated and the reference to the Perl
1222 subroutine, C<name> is copied to the variable C<keepSub> in one
1223 operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called
1224 the existing SV, C<keepSub>, is overwritten with the new value using
1227 =head2 Using call_argv
1229 Here is a Perl subroutine which prints whatever parameters are passed
1240 and here is an example of I<call_argv> which will call
1243 static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ;
1250 call_argv("PrintList", G_DISCARD, words) ;
1253 Note that it is not necessary to call C<PUSHMARK> in this instance.
1254 This is because I<call_argv> will do it for you.
1256 =head2 Using call_method
1258 Consider the following Perl code
1269 my ($self, $index) = @_;
1270 print "$index: $self->[$index]\n";
1275 print "This is Class $class version 1.0\n";
1279 It implements just a very simple class to manage an array. Apart from
1280 the constructor, C<new>, it declares methods, one static and one
1281 virtual. The static method, C<PrintID>, prints out simply the class
1282 name and a version number. The virtual method, C<Display>, prints out a
1283 single element of the array. Here is an all Perl example of using it.
1285 my $a = Mine->new('red', 'green', 'blue');
1293 This is Class Mine version 1.0
1295 Calling a Perl method from C is fairly straightforward. The following
1302 a reference to the object for a virtual method or the name of the class
1303 for a static method.
1307 the name of the method.
1311 any other parameters specific to the method.
1315 Here is a simple XSUB which illustrates the mechanics of calling both
1316 the C<PrintID> and C<Display> methods from C.
1319 call_Method(ref, method, index)
1326 XPUSHs(sv_2mortal(newSViv(index))) ;
1329 call_method(method, G_DISCARD) ;
1332 call_PrintID(class, method)
1337 XPUSHs(sv_2mortal(newSVpv(class, 0))) ;
1340 call_method(method, G_DISCARD) ;
1343 So the methods C<PrintID> and C<Display> can be invoked like this
1345 my $a = Mine->new('red', 'green', 'blue');
1346 call_Method($a, 'Display', 1);
1347 call_PrintID('Mine', 'PrintID');
1349 The only thing to note is that in both the static and virtual methods,
1350 the method name is not passed via the stack--it is used as the first
1351 parameter to I<call_method>.
1353 =head2 Using GIMME_V
1355 Here is a trivial XSUB which prints the context in which it is
1356 currently executing.
1361 I32 gimme = GIMME_V;
1362 if (gimme == G_VOID)
1363 printf ("Context is Void\n") ;
1364 else if (gimme == G_SCALAR)
1365 printf ("Context is Scalar\n") ;
1367 printf ("Context is Array\n") ;
1369 and here is some Perl to test it
1372 my $a = PrintContext;
1373 my @a = PrintContext;
1375 The output from that will be
1381 =head2 Using Perl to dispose of temporaries
1383 In the examples given to date, any temporaries created in the callback
1384 (i.e., parameters passed on the stack to the I<call_*> function or
1385 values returned via the stack) have been freed by one of these methods
1391 specifying the G_DISCARD flag with I<call_*>.
1395 explicitly disposed of using the C<ENTER>/C<SAVETMPS> -
1396 C<FREETMPS>/C<LEAVE> pairing.
1400 There is another method which can be used, namely letting Perl do it
1401 for you automatically whenever it regains control after the callback
1402 has terminated. This is done by simply not using the
1410 sequence in the callback (and not, of course, specifying the G_DISCARD
1413 If you are going to use this method you have to be aware of a possible
1414 memory leak which can arise under very specific circumstances. To
1415 explain these circumstances you need to know a bit about the flow of
1416 control between Perl and the callback routine.
1418 The examples given at the start of the document (an error handler and
1419 an event driven program) are typical of the two main sorts of flow
1420 control that you are likely to encounter with callbacks. There is a
1421 very important distinction between them, so pay attention.
1423 In the first example, an error handler, the flow of control could be as
1424 follows. You have created an interface to an external library.
1425 Control can reach the external library like this
1427 perl --> XSUB --> external library
1429 Whilst control is in the library, an error condition occurs. You have
1430 previously set up a Perl callback to handle this situation, so it will
1431 get executed. Once the callback has finished, control will drop back to
1432 Perl again. Here is what the flow of control will be like in that
1435 perl --> XSUB --> external library
1439 external library --> call_* --> perl
1441 perl <-- XSUB <-- external library <-- call_* <----+
1443 After processing of the error using I<call_*> is completed,
1444 control reverts back to Perl more or less immediately.
1446 In the diagram, the further right you go the more deeply nested the
1447 scope is. It is only when control is back with perl on the extreme
1448 left of the diagram that you will have dropped back to the enclosing
1449 scope and any temporaries you have left hanging around will be freed.
1451 In the second example, an event driven program, the flow of control
1452 will be more like this
1454 perl --> XSUB --> event handler
1456 event handler --> call_* --> perl
1458 event handler <-- call_* <----+
1460 event handler --> call_* --> perl
1462 event handler <-- call_* <----+
1464 event handler --> call_* --> perl
1466 event handler <-- call_* <----+
1468 In this case the flow of control can consist of only the repeated
1471 event handler --> call_* --> perl
1473 for practically the complete duration of the program. This means that
1474 control may I<never> drop back to the surrounding scope in Perl at the
1477 So what is the big problem? Well, if you are expecting Perl to tidy up
1478 those temporaries for you, you might be in for a long wait. For Perl
1479 to dispose of your temporaries, control must drop back to the
1480 enclosing scope at some stage. In the event driven scenario that may
1481 never happen. This means that as time goes on, your program will
1482 create more and more temporaries, none of which will ever be freed. As
1483 each of these temporaries consumes some memory your program will
1484 eventually consume all the available memory in your system--kapow!
1486 So here is the bottom line--if you are sure that control will revert
1487 back to the enclosing Perl scope fairly quickly after the end of your
1488 callback, then it isn't absolutely necessary to dispose explicitly of
1489 any temporaries you may have created. Mind you, if you are at all
1490 uncertain about what to do, it doesn't do any harm to tidy up anyway.
1493 =head2 Strategies for storing Callback Context Information
1496 Potentially one of the trickiest problems to overcome when designing a
1497 callback interface can be figuring out how to store the mapping between
1498 the C callback function and the Perl equivalent.
1500 To help understand why this can be a real problem first consider how a
1501 callback is set up in an all C environment. Typically a C API will
1502 provide a function to register a callback. This will expect a pointer
1503 to a function as one of its parameters. Below is a call to a
1504 hypothetical function C<register_fatal> which registers the C function
1505 to get called when a fatal error occurs.
1507 register_fatal(cb1) ;
1509 The single parameter C<cb1> is a pointer to a function, so you must
1510 have defined C<cb1> in your code, say something like this
1515 printf ("Fatal Error\n") ;
1519 Now change that to call a Perl subroutine instead
1521 static SV * callback = (SV*)NULL;
1530 /* Call the Perl sub to process the callback */
1531 call_sv(callback, G_DISCARD) ;
1539 /* Remember the Perl sub */
1540 if (callback == (SV*)NULL)
1541 callback = newSVsv(fn) ;
1543 SvSetSV(callback, fn) ;
1545 /* register the callback with the external library */
1546 register_fatal(cb1) ;
1548 where the Perl equivalent of C<register_fatal> and the callback it
1549 registers, C<pcb1>, might look like this
1551 # Register the sub pcb1
1552 register_fatal(\&pcb1) ;
1555 die "I'm dying...\n";
1558 The mapping between the C callback and the Perl equivalent is stored in
1559 the global variable C<callback>.
1561 This will be adequate if you ever need to have only one callback
1562 registered at any time. An example could be an error handler like the
1563 code sketched out above. Remember though, repeated calls to
1564 C<register_fatal> will replace the previously registered callback
1565 function with the new one.
1567 Say for example you want to interface to a library which allows asynchronous
1568 file i/o. In this case you may be able to register a callback whenever
1569 a read operation has completed. To be of any use we want to be able to
1570 call separate Perl subroutines for each file that is opened. As it
1571 stands, the error handler example above would not be adequate as it
1572 allows only a single callback to be defined at any time. What we
1573 require is a means of storing the mapping between the opened file and
1574 the Perl subroutine we want to be called for that file.
1576 Say the i/o library has a function C<asynch_read> which associates a C
1577 function C<ProcessRead> with a file handle C<fh>--this assumes that it
1578 has also provided some routine to open the file and so obtain the file
1581 asynch_read(fh, ProcessRead)
1583 This may expect the C I<ProcessRead> function of this form
1586 ProcessRead(fh, buffer)
1593 To provide a Perl interface to this library we need to be able to map
1594 between the C<fh> parameter and the Perl subroutine we want called. A
1595 hash is a convenient mechanism for storing this mapping. The code
1596 below shows a possible implementation
1598 static HV * Mapping = (HV*)NULL ;
1601 asynch_read(fh, callback)
1605 /* If the hash doesn't already exist, create it */
1606 if (Mapping == (HV*)NULL)
1609 /* Save the fh -> callback mapping */
1610 hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ;
1612 /* Register with the C Library */
1613 asynch_read(fh, asynch_read_if) ;
1615 and C<asynch_read_if> could look like this
1618 asynch_read_if(fh, buffer)
1625 /* Get the callback associated with fh */
1626 sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE) ;
1627 if (sv == (SV**)NULL)
1628 croak("Internal error...\n") ;
1631 XPUSHs(sv_2mortal(newSViv(fh))) ;
1632 XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1635 /* Call the Perl sub */
1636 call_sv(*sv, G_DISCARD) ;
1639 For completeness, here is C<asynch_close>. This shows how to remove
1640 the entry from the hash C<Mapping>.
1646 /* Remove the entry from the hash */
1647 (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ;
1649 /* Now call the real asynch_close */
1652 So the Perl interface would look like this
1655 my($handle, $buffer) = @_;
1658 # Register the Perl callback
1659 asynch_read($fh, \&callback1);
1663 The mapping between the C callback and Perl is stored in the global
1664 hash C<Mapping> this time. Using a hash has the distinct advantage that
1665 it allows an unlimited number of callbacks to be registered.
1667 What if the interface provided by the C callback doesn't contain a
1668 parameter which allows the file handle to Perl subroutine mapping? Say
1669 in the asynchronous i/o package, the callback function gets passed only
1670 the C<buffer> parameter like this
1679 Without the file handle there is no straightforward way to map from the
1680 C callback to the Perl subroutine.
1682 In this case a possible way around this problem is to predefine a
1683 series of C functions to act as the interface to Perl, thus
1686 #define NULL_HANDLE -1
1687 typedef void (*FnMap)() ;
1699 static struct MapStruct Map [MAX_CB] =
1701 { fn1, NULL, NULL_HANDLE },
1702 { fn2, NULL, NULL_HANDLE },
1703 { fn3, NULL, NULL_HANDLE }
1714 XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1717 /* Call the Perl sub */
1718 call_sv(Map[index].PerlSub, G_DISCARD) ;
1743 array_asynch_read(fh, callback)
1748 int null_index = MAX_CB ;
1750 /* Find the same handle or an empty entry */
1751 for (index = 0 ; index < MAX_CB ; ++index)
1753 if (Map[index].Handle == fh)
1756 if (Map[index].Handle == NULL_HANDLE)
1757 null_index = index ;
1760 if (index == MAX_CB && null_index == MAX_CB)
1761 croak ("Too many callback functions registered\n") ;
1763 if (index == MAX_CB)
1764 index = null_index ;
1766 /* Save the file handle */
1767 Map[index].Handle = fh ;
1769 /* Remember the Perl sub */
1770 if (Map[index].PerlSub == (SV*)NULL)
1771 Map[index].PerlSub = newSVsv(callback) ;
1773 SvSetSV(Map[index].PerlSub, callback) ;
1775 asynch_read(fh, Map[index].Function) ;
1778 array_asynch_close(fh)
1783 /* Find the file handle */
1784 for (index = 0; index < MAX_CB ; ++ index)
1785 if (Map[index].Handle == fh)
1788 if (index == MAX_CB)
1789 croak ("could not close fh %d\n", fh) ;
1791 Map[index].Handle = NULL_HANDLE ;
1792 SvREFCNT_dec(Map[index].PerlSub) ;
1793 Map[index].PerlSub = (SV*)NULL ;
1797 In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to
1798 remember the Perl subroutine to be called. Each of the functions holds
1799 a separate hard-wired index which is used in the function C<Pcb> to
1800 access the C<Map> array and actually call the Perl subroutine.
1802 There are some obvious disadvantages with this technique.
1804 Firstly, the code is considerably more complex than with the previous
1807 Secondly, there is a hard-wired limit (in this case 3) to the number of
1808 callbacks that can exist simultaneously. The only way to increase the
1809 limit is by modifying the code to add more functions and then
1810 recompiling. None the less, as long as the number of functions is
1811 chosen with some care, it is still a workable solution and in some
1812 cases is the only one available.
1814 To summarize, here are a number of possible methods for you to consider
1815 for storing the mapping between C and the Perl callback
1819 =item 1. Ignore the problem - Allow only 1 callback
1821 For a lot of situations, like interfacing to an error handler, this may
1822 be a perfectly adequate solution.
1824 =item 2. Create a sequence of callbacks - hard wired limit
1826 If it is impossible to tell from the parameters passed back from the C
1827 callback what the context is, then you may need to create a sequence of C
1828 callback interface functions, and store pointers to each in an array.
1830 =item 3. Use a parameter to map to the Perl callback
1832 A hash is an ideal mechanism to store the mapping between C and Perl.
1837 =head2 Alternate Stack Manipulation
1840 Although I have made use of only the C<POP*> macros to access values
1841 returned from Perl subroutines, it is also possible to bypass these
1842 macros and read the stack using the C<ST> macro (See L<perlxs> for a
1843 full description of the C<ST> macro).
1845 Most of the time the C<POP*> macros should be adequate, the main
1846 problem with them is that they force you to process the returned values
1847 in sequence. This may not be the most suitable way to process the
1848 values in some cases. What we want is to be able to access the stack in
1849 a random order. The C<ST> macro as used when coding an XSUB is ideal
1852 The code below is the example given in the section I<Returning a list
1853 of values> recoded to use C<ST> instead of C<POP*>.
1856 call_AddSubtract2(a, b)
1868 XPUSHs(sv_2mortal(newSViv(a)));
1869 XPUSHs(sv_2mortal(newSViv(b)));
1872 count = call_pv("AddSubtract", G_ARRAY);
1876 ax = (SP - PL_stack_base) + 1 ;
1879 croak("Big trouble\n") ;
1881 printf ("%d + %d = %d\n", a, b, SvIV(ST(0))) ;
1882 printf ("%d - %d = %d\n", a, b, SvIV(ST(1))) ;
1895 Notice that it was necessary to define the variable C<ax>. This is
1896 because the C<ST> macro expects it to exist. If we were in an XSUB it
1897 would not be necessary to define C<ax> as it is already defined for
1906 ax = (SP - PL_stack_base) + 1 ;
1908 sets the stack up so that we can use the C<ST> macro.
1912 Unlike the original coding of this example, the returned
1913 values are not accessed in reverse order. So C<ST(0)> refers to the
1914 first value returned by the Perl subroutine and C<ST(count-1)>
1919 =head2 Creating and calling an anonymous subroutine in C
1921 As we've already shown, C<call_sv> can be used to invoke an
1922 anonymous subroutine. However, our example showed a Perl script
1923 invoking an XSUB to perform this operation. Let's see how it can be
1924 done inside our C code:
1928 SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);
1932 call_sv(cvrv, G_VOID|G_NOARGS);
1934 C<eval_pv> is used to compile the anonymous subroutine, which
1935 will be the return value as well (read more about C<eval_pv> in
1936 L<perlapi/eval_pv>). Once this code reference is in hand, it
1937 can be mixed in with all the previous examples we've shown.
1941 L<perlxs>, L<perlguts>, L<perlembed>
1947 Special thanks to the following people who assisted in the creation of
1950 Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
1955 Version 1.3, 14th Apr 1997