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, such as for an X11 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--L<perlxs>
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, 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, L</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 L</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 one of C<G_VOID>,
125 C<G_SCALAR>, or C<G_LIST>, which indicate the call context, OR'ed together
126 with a bit mask of any combination of the other G_* symbols defined below.
130 =for apidoc AmnUh||G_VOID
132 Calls the Perl subroutine in a void context.
134 This flag has 2 effects:
140 It indicates to the subroutine being called that it is executing in
141 a void context (if it executes I<wantarray> the result will be the
146 It ensures that nothing is actually returned from the subroutine.
150 The value returned by the I<call_*> function indicates how many
151 items have been returned by the Perl subroutine--in this case it will
157 =for apidoc AmnUh||G_SCALAR
159 Calls the Perl subroutine in a scalar context. This is the default
160 context flag setting for all the I<call_*> functions.
162 This flag has 2 effects:
168 It indicates to the subroutine being called that it is executing in a
169 scalar context (if it executes I<wantarray> the result will be false).
173 It ensures that only a scalar is actually returned from the subroutine.
174 The subroutine can, of course, ignore the I<wantarray> and return a
175 list anyway. If so, then only the last element of the list will be
180 The value returned by the I<call_*> function indicates how many
181 items have been returned by the Perl subroutine - in this case it will
184 If 0, then you have specified the G_DISCARD flag.
186 If 1, then the item actually returned by the Perl subroutine will be
187 stored on the Perl stack - the section L</Returning a Scalar> shows how
188 to access this value on the stack. Remember that regardless of how
189 many items the Perl subroutine returns, only the last one will be
190 accessible from the stack - think of the case where only one value is
191 returned as being a list with only one element. Any other items that
192 were returned will not exist by the time control returns from the
193 I<call_*> function. The section L</Returning a List in Scalar
194 Context> shows an example of this behavior.
199 =for apidoc AmnUh||G_LIST
201 Calls the Perl subroutine in a list context. Prior to Perl version
202 5.35.1 this was called C<G_ARRAY>.
204 As with G_SCALAR, this flag has 2 effects:
210 It indicates to the subroutine being called that it is executing in a
211 list context (if it executes I<wantarray> the result will be true).
215 It ensures that all items returned from the subroutine will be
216 accessible when control returns from the I<call_*> function.
220 The value returned by the I<call_*> function indicates how many
221 items have been returned by the Perl subroutine.
223 If 0, then you have specified the G_DISCARD flag.
225 If not 0, then it will be a count of the number of items returned by
226 the subroutine. These items will be stored on the Perl stack. The
227 section L</Returning a List of Values> gives an example of using the
228 G_LIST flag and the mechanics of accessing the returned items from the
233 =for apidoc AmnUh||G_DISCARD
235 By default, the I<call_*> functions place the items returned from
236 by the Perl subroutine on the stack. If you are not interested in
237 these items, then setting this flag will make Perl get rid of them
238 automatically for you. Note that it is still possible to indicate a
239 context to the Perl subroutine by using either G_SCALAR or G_LIST.
241 If you do not set this flag then it is I<very> important that you make
242 sure that any temporaries (i.e., parameters passed to the Perl
243 subroutine and values returned from the subroutine) are disposed of
244 yourself. The section L</Returning a Scalar> gives details of how to
245 dispose of these temporaries explicitly and the section L</Using Perl to
246 Dispose of Temporaries> discusses the specific circumstances where you
247 can ignore the problem and let Perl deal with it for you.
251 =for apidoc AmnUh||G_NOARGS
253 Whenever a Perl subroutine is called using one of the I<call_*>
254 functions, it is assumed by default that parameters are to be passed to
255 the subroutine. If you are not passing any parameters to the Perl
256 subroutine, you can save a bit of time by setting this flag. It has
257 the effect of not creating the C<@_> array for the Perl subroutine.
259 Although the functionality provided by this flag may seem
260 straightforward, it should be used only if there is a good reason to do
261 so. The reason for being cautious is that, even if you have specified
262 the G_NOARGS flag, it is still possible for the Perl subroutine that
263 has been called to think that you have passed it parameters.
265 In fact, what can happen is that the Perl subroutine you have called
266 can access the C<@_> array from a previous Perl subroutine. This will
267 occur when the code that is executing the I<call_*> function has
268 itself been called from another Perl subroutine. The code below
283 What has happened is that C<fred> accesses the C<@_> array which
289 =for apidoc AmnUh||G_EVAL
291 It is possible for the Perl subroutine you are calling to terminate
292 abnormally, e.g., by calling I<die> explicitly or by not actually
293 existing. By default, when either of these events occurs, the
294 process will terminate immediately. If you want to trap this
295 type of event, specify the G_EVAL flag. It will put an I<eval { }>
296 around the subroutine call.
298 Whenever control returns from the I<call_*> function you need to
299 check the C<$@> variable as you would in a normal Perl script.
301 The value returned from the I<call_*> function is dependent on
302 what other flags have been specified and whether an error has
303 occurred. Here are all the different cases that can occur:
309 If the I<call_*> function returns normally, then the value
310 returned is as specified in the previous sections.
314 If G_DISCARD is specified, the return value will always be 0.
318 If G_LIST is specified I<and> an error has occurred, the return value
323 If G_SCALAR is specified I<and> an error has occurred, the return value
324 will be 1 and the value on the top of the stack will be I<undef>. This
325 means that if you have already detected the error by checking C<$@> and
326 you want the program to continue, you must remember to pop the I<undef>
331 See L</Using G_EVAL> for details on using G_EVAL.
335 =for apidoc AmnUh||G_KEEPERR
337 Using the G_EVAL flag described above will always set C<$@>: clearing
338 it if there was no error, and setting it to describe the error if there
339 was an error in the called code. This is what you want if your intention
340 is to handle possible errors, but sometimes you just want to trap errors
341 and stop them interfering with the rest of the program.
343 This scenario will mostly be applicable to code that is meant to be called
344 from within destructors, asynchronous callbacks, and signal handlers.
345 In such situations, where the code being called has little relation to the
346 surrounding dynamic context, the main program needs to be insulated from
347 errors in the called code, even if they can't be handled intelligently.
348 It may also be useful to do this with code for C<__DIE__> or C<__WARN__>
349 hooks, and C<tie> functions.
351 The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
352 I<call_*> functions that are used to implement such code, or with
353 C<eval_sv>. This flag has no effect on the C<call_*> functions when
356 When G_KEEPERR is used, any error in the called code will terminate the
357 call as usual, and the error will not propagate beyond the call (as usual
358 for G_EVAL), but it will not go into C<$@>. Instead the error will be
359 converted into a warning, prefixed with the string "\t(in cleanup)".
360 This can be disabled using C<no warnings 'misc'>. If there is no error,
361 C<$@> will not be cleared.
363 Note that the G_KEEPERR flag does not propagate into inner evals; these
366 The G_KEEPERR flag was introduced in Perl version 5.002.
368 See L</Using G_KEEPERR> for an example of a situation that warrants the
371 =head2 Determining the Context
373 As mentioned above, you can determine the context of the currently
374 executing subroutine in Perl with I<wantarray>. The equivalent test
375 can be made in C by using the C<GIMME_V> macro, which returns
376 C<G_LIST> if you have been called in a list context, C<G_SCALAR> if
377 in a scalar context, or C<G_VOID> if in a void context (i.e., the
378 return value will not be used). An older version of this macro is
379 called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
380 C<G_VOID>. An example of using the C<GIMME_V> macro is shown in
381 section L</Using GIMME_V>.
385 Enough of the definition talk! Let's have a few examples.
387 Perl provides many macros to assist in accessing the Perl stack.
388 Wherever possible, these macros should always be used when interfacing
389 to Perl internals. We hope this should make the code less vulnerable
390 to any changes made to Perl in the future.
392 Another point worth noting is that in the first series of examples I
393 have made use of only the I<call_pv> function. This has been done
394 to keep the code simpler and ease you into the topic. Wherever
395 possible, if the choice is between using I<call_pv> and
396 I<call_sv>, you should always try to use I<call_sv>. See
397 L</Using call_sv> for details.
399 =head2 No Parameters, Nothing Returned
401 This first trivial example will call a Perl subroutine, I<PrintUID>, to
402 print out the UID of the process.
409 and here is a C function to call it
417 call_pv("PrintUID", G_DISCARD|G_NOARGS);
422 A few points to note about this example:
428 Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
433 We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
438 We aren't interested in anything returned from I<PrintUID>, so
439 G_DISCARD is specified. Even if I<PrintUID> was changed to
440 return some value(s), having specified G_DISCARD will mean that they
441 will be wiped by the time control returns from I<call_pv>.
445 As I<call_pv> is being used, the Perl subroutine is specified as a
446 C string. In this case the subroutine name has been 'hard-wired' into the
451 Because we specified G_DISCARD, it is not necessary to check the value
452 returned from I<call_pv>. It will always be 0.
456 =head2 Passing Parameters
458 Now let's make a slightly more complex example. This time we want to
459 call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
460 string ($s) and an integer ($n). The subroutine will simply
461 print the first $n characters of the string.
463 So the Perl subroutine would look like this:
468 print substr($s, 0, $n), "\n";
471 The C function required to call I<LeftString> would look like this:
474 call_LeftString(a, b)
485 PUSHs(sv_2mortal(newSVpv(a, 0)));
486 PUSHs(sv_2mortal(newSViv(b)));
489 call_pv("LeftString", G_DISCARD);
495 Here are a few notes on the C function I<call_LeftString>.
501 Parameters are passed to the Perl subroutine using the Perl stack.
502 This is the purpose of the code beginning with the line C<dSP> and
503 ending with the line C<PUTBACK>. The C<dSP> declares a local copy
504 of the stack pointer. This local copy should B<always> be accessed
509 If you are going to put something onto the Perl stack, you need to know
510 where to put it. This is the purpose of the macro C<dSP>--it declares
511 and initializes a I<local> copy of the Perl stack pointer.
513 All the other macros which will be used in this example require you to
514 have used this macro.
516 The exception to this rule is if you are calling a Perl subroutine
517 directly from an XSUB function. In this case it is not necessary to
518 use the C<dSP> macro explicitly--it will be declared for you
523 Any parameters to be pushed onto the stack should be bracketed by the
524 C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
525 this context, is to count the number of parameters you are
526 pushing automatically. Then whenever Perl is creating the C<@_> array for the
527 subroutine, it knows how big to make it.
529 The C<PUSHMARK> macro tells Perl to make a mental note of the current
530 stack pointer. Even if you aren't passing any parameters (like the
531 example shown in the section L</No Parameters, Nothing Returned>) you
532 must still call the C<PUSHMARK> macro before you can call any of the
533 I<call_*> functions--Perl still needs to know that there are no
536 The C<PUTBACK> macro sets the global copy of the stack pointer to be
537 the same as our local copy. If we didn't do this, I<call_pv>
538 wouldn't know where the two parameters we pushed were--remember that
539 up to now all the stack pointer manipulation we have done is with our
540 local copy, I<not> the global copy.
544 Next, we come to EXTEND and PUSHs. This is where the parameters
545 actually get pushed onto the stack. In this case we are pushing a
546 string and an integer.
548 Alternatively you can use the XPUSHs() macro, which combines a
549 C<EXTEND(SP, 1)> and C<PUSHs()>. This is less efficient if you're
550 pushing multiple values.
552 See L<perlguts/"XSUBs and the Argument Stack"> for details
553 on how the PUSH macros work.
557 Because we created temporary values (by means of sv_2mortal() calls)
558 we will have to tidy up the Perl stack and dispose of mortal SVs.
560 This is the purpose of
565 at the start of the function, and
570 at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
571 temporaries we create. This means that the temporaries we get rid of
572 will be limited to those which were created after these calls.
574 The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
575 the Perl subroutine (see next example), plus it will also dump the
576 mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the
577 beginning of the code makes sure that no other mortals are destroyed.
579 Think of these macros as working a bit like C<{> and C<}> in Perl
580 to limit the scope of local variables.
582 See the section L</Using Perl to Dispose of Temporaries> for details of
583 an alternative to using these macros.
587 Finally, I<LeftString> can now be called via the I<call_pv> function.
588 The only flag specified this time is G_DISCARD. Because we are passing
589 2 parameters to the Perl subroutine this time, we have not specified
594 =head2 Returning a Scalar
596 Now for an example of dealing with the items returned from a Perl
599 Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
600 and simply returns their sum.
608 Because we are now concerned with the return value from I<Adder>, the C
609 function required to call it is now a bit more complex.
624 PUSHs(sv_2mortal(newSViv(a)));
625 PUSHs(sv_2mortal(newSViv(b)));
628 count = call_pv("Adder", G_SCALAR);
633 croak("Big trouble\n");
635 printf ("The sum of %d and %d is %d\n", a, b, POPi);
642 Points to note this time are
648 The only flag specified this time was G_SCALAR. That means that the C<@_>
649 array will be created and that the value returned by I<Adder> will
650 still exist after the call to I<call_pv>.
654 The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
655 stack pointer. This is necessary because it is possible that the memory
656 allocated to the Perl stack has been reallocated during the
659 If you are making use of the Perl stack pointer in your code you must
660 always refresh the local copy using SPAGAIN whenever you make use
661 of the I<call_*> functions or any other Perl internal function.
665 Although only a single value was expected to be returned from I<Adder>,
666 it is still good practice to check the return code from I<call_pv>
669 Expecting a single value is not quite the same as knowing that there
670 will be one. If someone modified I<Adder> to return a list and we
671 didn't check for that possibility and take appropriate action the Perl
672 stack would end up in an inconsistent state. That is something you
673 I<really> don't want to happen ever.
677 The C<POPi> macro is used here to pop the return value from the stack.
678 In this case we wanted an integer, so C<POPi> was used.
681 Here is the complete list of POP macros available, along with the types
686 POPpbytex pointer to bytes (PV)
689 POPu unsigned integer (UV)
693 Since these macros have side-effects don't use them as arguments to
694 macros that may evaluate their argument several times, for example:
696 /* Bad idea, don't do this */
698 const char *s = SvPV(POPs, len);
700 Instead, use a temporary:
704 const char *s = SvPV(sv, len);
706 or a macro that guarantees it will evaluate its arguments only once:
709 const char *s = SvPVx(POPs, len);
713 The final C<PUTBACK> is used to leave the Perl stack in a consistent
714 state before exiting the function. This is necessary because when we
715 popped the return value from the stack with C<POPi> it updated only our
716 local copy of the stack pointer. Remember, C<PUTBACK> sets the global
717 stack pointer to be the same as our local copy.
722 =head2 Returning a List of Values
724 Now, let's extend the previous example to return both the sum of the
725 parameters and the difference.
727 Here is the Perl subroutine
735 and this is the C function
738 call_AddSubtract(a, b)
750 PUSHs(sv_2mortal(newSViv(a)));
751 PUSHs(sv_2mortal(newSViv(b)));
754 count = call_pv("AddSubtract", G_LIST);
759 croak("Big trouble\n");
761 printf ("%d - %d = %d\n", a, b, POPi);
762 printf ("%d + %d = %d\n", a, b, POPi);
769 If I<call_AddSubtract> is called like this
771 call_AddSubtract(7, 4);
773 then here is the output
784 We wanted list context, so G_LIST was used.
788 Not surprisingly C<POPi> is used twice this time because we were
789 retrieving 2 values from the stack. The important thing to note is that
790 when using the C<POP*> macros they come off the stack in I<reverse>
795 =head2 Returning a List in Scalar Context
797 Say the Perl subroutine in the previous section was called in a scalar
801 call_AddSubScalar(a, b)
814 PUSHs(sv_2mortal(newSViv(a)));
815 PUSHs(sv_2mortal(newSViv(b)));
818 count = call_pv("AddSubtract", G_SCALAR);
822 printf ("Items Returned = %d\n", count);
824 for (i = 1; i <= count; ++i)
825 printf ("Value %d = %d\n", i, POPi);
832 The other modification made is that I<call_AddSubScalar> will print the
833 number of items returned from the Perl subroutine and their value (for
834 simplicity it assumes that they are integer). So if
835 I<call_AddSubScalar> is called
837 call_AddSubScalar(7, 4);
839 then the output will be
844 In this case the main point to note is that only the last item in the
845 list is returned from the subroutine. I<AddSubtract> actually made it back to
846 I<call_AddSubScalar>.
849 =head2 Returning Data from Perl via the Parameter List
851 It is also possible to return values directly via the parameter
852 list--whether it is actually desirable to do it is another matter entirely.
854 The Perl subroutine, I<Inc>, below takes 2 parameters and increments
863 and here is a C function to call it.
878 sva = sv_2mortal(newSViv(a));
879 svb = sv_2mortal(newSViv(b));
887 count = call_pv("Inc", G_DISCARD);
890 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
893 printf ("%d + 1 = %d\n", a, SvIV(sva));
894 printf ("%d + 1 = %d\n", b, SvIV(svb));
900 To be able to access the two parameters that were pushed onto the stack
901 after they return from I<call_pv> it is necessary to make a note
902 of their addresses--thus the two variables C<sva> and C<svb>.
904 The reason this is necessary is that the area of the Perl stack which
905 held them will very likely have been overwritten by something else by
906 the time control returns from I<call_pv>.
913 Now an example using G_EVAL. Below is a Perl subroutine which computes
914 the difference of its 2 parameters. If this would result in a negative
915 result, the subroutine calls I<die>.
921 die "death can be fatal\n" if $a < $b;
926 and some C to call it
942 PUSHs(sv_2mortal(newSViv(a)));
943 PUSHs(sv_2mortal(newSViv(b)));
946 count = call_pv("Subtract", G_EVAL|G_SCALAR);
950 /* Check the eval first */
954 printf ("Uh oh - %s\n", SvPV_nolen(err_tmp));
960 croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
963 printf ("%d - %d = %d\n", a, b, POPi);
971 If I<call_Subtract> is called thus
975 the following will be printed
977 Uh oh - death can be fatal
985 We want to be able to catch the I<die> so we have used the G_EVAL
986 flag. Not specifying this flag would mean that the program would
987 terminate immediately at the I<die> statement in the subroutine
997 printf ("Uh oh - %s\n", SvPV_nolen(err_tmp));
1001 is the direct equivalent of this bit of Perl
1003 print "Uh oh - $@\n" if $@;
1005 C<PL_errgv> is a perl global of type C<GV *> that points to the symbol
1006 table entry containing the error. C<ERRSV> therefore refers to the C
1007 equivalent of C<$@>. We use a local temporary, C<err_tmp>, since
1008 C<ERRSV> is a macro that calls a function, and C<SvTRUE(ERRSV)> would
1009 end up calling that function multiple times.
1011 =for apidoc AmnUh|GV *|PL_errgv
1015 Note that the stack is popped using C<POPs> in the block where
1016 C<SvTRUE(err_tmp)> is true. This is necessary because whenever a
1017 I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
1018 the top of the stack holds the value I<undef>. Because we want the
1019 program to continue after detecting this error, it is essential that
1020 the stack be tidied up by removing the I<undef>.
1025 =head2 Using G_KEEPERR
1027 Consider this rather facetious example, where we have used an XS
1028 version of the call_Subtract example above inside a destructor:
1031 sub new { bless {}, $_[0] }
1034 die "death can be fatal" if $a < $b;
1037 sub DESTROY { call_Subtract(5, 4); }
1038 sub foo { die "foo dies"; }
1045 print "Saw: $@" if $@; # should be, but isn't
1047 This example will fail to recognize that an error occurred inside the
1048 C<eval {}>. Here's why: the call_Subtract code got executed while perl
1049 was cleaning up temporaries when exiting the outer braced block, and because
1050 call_Subtract is implemented with I<call_pv> using the G_EVAL
1051 flag, it promptly reset C<$@>. This results in the failure of the
1052 outermost test for C<$@>, and thereby the failure of the error trap.
1054 Appending the G_KEEPERR flag, so that the I<call_pv> call in
1055 call_Subtract reads:
1057 count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
1059 will preserve the error and restore reliable error handling.
1061 =head2 Using call_sv
1063 In all the previous examples I have 'hard-wired' the name of the Perl
1064 subroutine to be called from C. Most of the time though, it is more
1065 convenient to be able to specify the name of the Perl subroutine from
1066 within the Perl script, and you'll want to use
1067 L<call_sv|perlapi/call_sv>.
1069 Consider the Perl code below
1073 print "Hello there\n";
1078 Here is a snippet of XSUB which defines I<CallSubPV>.
1085 call_pv(name, G_DISCARD|G_NOARGS);
1087 That is fine as far as it goes. The thing is, the Perl subroutine
1088 can be specified as only a string, however, Perl allows references
1089 to subroutines and anonymous subroutines.
1090 This is where I<call_sv> is useful.
1092 The code below for I<CallSubSV> is identical to I<CallSubPV> except
1093 that the C<name> parameter is now defined as an SV* and we use
1094 I<call_sv> instead of I<call_pv>.
1101 call_sv(name, G_DISCARD|G_NOARGS);
1103 Because we are using an SV to call I<fred> the following can all be used:
1109 CallSubSV( sub { print "Hello there\n" } );
1111 As you can see, I<call_sv> gives you much greater flexibility in
1112 how you can specify the Perl subroutine.
1114 You should note that, if it is necessary to store the SV (C<name> in the
1115 example above) which corresponds to the Perl subroutine so that it can
1116 be used later in the program, it not enough just to store a copy of the
1117 pointer to the SV. Say the code above had been like this:
1119 static SV * rememberSub;
1131 call_sv(rememberSub, G_DISCARD|G_NOARGS);
1133 The reason this is wrong is that, by the time you come to use the
1134 pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1135 to the Perl subroutine that was recorded in C<SaveSub1>. This is
1136 particularly true for these cases:
1141 SaveSub1( sub { print "Hello there\n" } );
1144 By the time each of the C<SaveSub1> statements above has been executed,
1145 the SV*s which corresponded to the parameters will no longer exist.
1146 Expect an error message from Perl of the form
1148 Can't use an undefined value as a subroutine reference at ...
1150 for each of the C<CallSavedSub1> lines.
1152 Similarly, with this code
1159 you can expect one of these messages (which you actually get is dependent on
1160 the version of Perl you are using)
1162 Not a CODE reference at ...
1163 Undefined subroutine &main::47 called ...
1165 The variable $ref may have referred to the subroutine C<fred>
1166 whenever the call to C<SaveSub1> was made but by the time
1167 C<CallSavedSub1> gets called it now holds the number C<47>. Because we
1168 saved only a pointer to the original SV in C<SaveSub1>, any changes to
1169 $ref will be tracked by the pointer C<rememberSub>. This means that
1170 whenever C<CallSavedSub1> gets called, it will attempt to execute the
1171 code which is referenced by the SV* C<rememberSub>. In this case
1172 though, it now refers to the integer C<47>, so expect Perl to complain
1175 A similar but more subtle problem is illustrated with this code:
1182 This time whenever C<CallSavedSub1> gets called it will execute the Perl
1183 subroutine C<joe> (assuming it exists) rather than C<fred> as was
1184 originally requested in the call to C<SaveSub1>.
1186 To get around these problems it is necessary to take a full copy of the
1187 SV. The code below shows C<SaveSub2> modified to do that.
1189 /* this isn't thread-safe */
1190 static SV * keepSub = (SV*)NULL;
1196 /* Take a copy of the callback */
1197 if (keepSub == (SV*)NULL)
1198 /* First time, so create a new SV */
1199 keepSub = newSVsv(name);
1201 /* Been here before, so overwrite */
1202 SvSetSV(keepSub, name);
1208 call_sv(keepSub, G_DISCARD|G_NOARGS);
1210 To avoid creating a new SV every time C<SaveSub2> is called,
1211 the function first checks to see if it has been called before. If not,
1212 then space for a new SV is allocated and the reference to the Perl
1213 subroutine C<name> is copied to the variable C<keepSub> in one
1214 operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called,
1215 the existing SV, C<keepSub>, is overwritten with the new value using
1218 Note: using a static or global variable to store the SV isn't
1219 thread-safe. You can either use the C<MY_CXT> mechanism documented in
1220 L<perlxs/Safely Storing Static Data in XS> which is fast, or store the
1221 values in perl global variables, using get_sv(), which is much slower.
1223 =head2 Using call_argv
1225 Here is a Perl subroutine which prints whatever parameters are passed
1232 foreach (@list) { print "$_\n" }
1235 And here is an example of I<call_argv> which will call
1238 static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
1243 call_argv("PrintList", G_DISCARD, words);
1246 Note that it is not necessary to call C<PUSHMARK> in this instance.
1247 This is because I<call_argv> will do it for you.
1249 =head2 Using call_method
1251 Consider the following Perl code:
1264 my ($self, $index) = @_;
1265 print "$index: $$self[$index]\n";
1271 print "This is Class $class version 1.0\n";
1275 It implements just a very simple class to manage an array. Apart from
1276 the constructor, C<new>, it declares methods, one static and one
1277 virtual. The static method, C<PrintID>, prints out simply the class
1278 name and a version number. The virtual method, C<Display>, prints out a
1279 single element of the array. Here is an all-Perl example of using it.
1281 $a = Mine->new('red', 'green', 'blue');
1288 This is Class Mine version 1.0
1290 Calling a Perl method from C is fairly straightforward. The following
1291 things are required:
1297 A reference to the object for a virtual method or the name of the class
1302 The name of the method
1306 Any other parameters specific to the method
1310 Here is a simple XSUB which illustrates the mechanics of calling both
1311 the C<PrintID> and C<Display> methods from C.
1314 call_Method(ref, method, index)
1322 PUSHs(sv_2mortal(newSViv(index)));
1325 call_method(method, G_DISCARD);
1328 call_PrintID(class, method)
1333 XPUSHs(sv_2mortal(newSVpv(class, 0)));
1336 call_method(method, G_DISCARD);
1339 So the methods C<PrintID> and C<Display> can be invoked like this:
1341 $a = Mine->new('red', 'green', 'blue');
1342 call_Method($a, 'Display', 1);
1343 call_PrintID('Mine', 'PrintID');
1345 The only thing to note is that, in both the static and virtual methods,
1346 the method name is not passed via the stack--it is used as the first
1347 parameter to I<call_method>.
1349 =head2 Using GIMME_V
1351 Here is a trivial XSUB which prints the context in which it is
1352 currently executing.
1358 if (gimme == G_VOID)
1359 printf ("Context is Void\n");
1360 else if (gimme == G_SCALAR)
1361 printf ("Context is Scalar\n");
1363 printf ("Context is Array\n");
1365 And here is some Perl to test it.
1371 The output from that will be
1377 =head2 Using Perl to Dispose of Temporaries
1379 In the examples given to date, any temporaries created in the callback
1380 (i.e., parameters passed on the stack to the I<call_*> function or
1381 values returned via the stack) have been freed by one of these methods:
1387 Specifying the G_DISCARD flag with I<call_*>
1391 Explicitly using the C<ENTER>/C<SAVETMPS>--C<FREETMPS>/C<LEAVE> pairing
1395 There is another method which can be used, namely letting Perl do it
1396 for you automatically whenever it regains control after the callback
1397 has terminated. This is done by simply not using the
1405 sequence in the callback (and not, of course, specifying the G_DISCARD
1408 If you are going to use this method you have to be aware of a possible
1409 memory leak which can arise under very specific circumstances. To
1410 explain these circumstances you need to know a bit about the flow of
1411 control between Perl and the callback routine.
1413 The examples given at the start of the document (an error handler and
1414 an event driven program) are typical of the two main sorts of flow
1415 control that you are likely to encounter with callbacks. There is a
1416 very important distinction between them, so pay attention.
1418 In the first example, an error handler, the flow of control could be as
1419 follows. You have created an interface to an external library.
1420 Control can reach the external library like this
1422 perl --> XSUB --> external library
1424 Whilst control is in the library, an error condition occurs. You have
1425 previously set up a Perl callback to handle this situation, so it will
1426 get executed. Once the callback has finished, control will drop back to
1427 Perl again. Here is what the flow of control will be like in that
1430 perl --> XSUB --> external library
1434 external library --> call_* --> perl
1436 perl <-- XSUB <-- external library <-- call_* <----+
1438 After processing of the error using I<call_*> is completed,
1439 control reverts back to Perl more or less immediately.
1441 In the diagram, the further right you go the more deeply nested the
1442 scope is. It is only when control is back with perl on the extreme
1443 left of the diagram that you will have dropped back to the enclosing
1444 scope and any temporaries you have left hanging around will be freed.
1446 In the second example, an event driven program, the flow of control
1447 will be more like this
1449 perl --> XSUB --> event handler
1451 event handler --> call_* --> perl
1453 event handler <-- call_* <----+
1455 event handler --> call_* --> perl
1457 event handler <-- call_* <----+
1459 event handler --> call_* --> perl
1461 event handler <-- call_* <----+
1463 In this case the flow of control can consist of only the repeated
1466 event handler --> call_* --> perl
1468 for practically the complete duration of the program. This means that
1469 control may I<never> drop back to the surrounding scope in Perl at the
1472 So what is the big problem? Well, if you are expecting Perl to tidy up
1473 those temporaries for you, you might be in for a long wait. For Perl
1474 to dispose of your temporaries, control must drop back to the
1475 enclosing scope at some stage. In the event driven scenario that may
1476 never happen. This means that, as time goes on, your program will
1477 create more and more temporaries, none of which will ever be freed. As
1478 each of these temporaries consumes some memory your program will
1479 eventually consume all the available memory in your system--kapow!
1481 So here is the bottom line--if you are sure that control will revert
1482 back to the enclosing Perl scope fairly quickly after the end of your
1483 callback, then it isn't absolutely necessary to dispose explicitly of
1484 any temporaries you may have created. Mind you, if you are at all
1485 uncertain about what to do, it doesn't do any harm to tidy up anyway.
1488 =head2 Strategies for Storing Callback Context Information
1491 Potentially one of the trickiest problems to overcome when designing a
1492 callback interface can be figuring out how to store the mapping between
1493 the C callback function and the Perl equivalent.
1495 To help understand why this can be a real problem first consider how a
1496 callback is set up in an all C environment. Typically a C API will
1497 provide a function to register a callback. This will expect a pointer
1498 to a function as one of its parameters. Below is a call to a
1499 hypothetical function C<register_fatal> which registers the C function
1500 to get called when a fatal error occurs.
1502 register_fatal(cb1);
1504 The single parameter C<cb1> is a pointer to a function, so you must
1505 have defined C<cb1> in your code, say something like this
1510 printf ("Fatal Error\n");
1514 Now change that to call a Perl subroutine instead
1516 static SV * callback = (SV*)NULL;
1525 /* Call the Perl sub to process the callback */
1526 call_sv(callback, G_DISCARD);
1534 /* Remember the Perl sub */
1535 if (callback == (SV*)NULL)
1536 callback = newSVsv(fn);
1538 SvSetSV(callback, fn);
1540 /* register the callback with the external library */
1541 register_fatal(cb1);
1543 where the Perl equivalent of C<register_fatal> and the callback it
1544 registers, C<pcb1>, might look like this
1546 # Register the sub pcb1
1547 register_fatal(\&pcb1);
1551 die "I'm dying...\n";
1554 The mapping between the C callback and the Perl equivalent is stored in
1555 the global variable C<callback>.
1557 This will be adequate if you ever need to have only one callback
1558 registered at any time. An example could be an error handler like the
1559 code sketched out above. Remember though, repeated calls to
1560 C<register_fatal> will replace the previously registered callback
1561 function with the new one.
1563 Say for example you want to interface to a library which allows asynchronous
1564 file i/o. In this case you may be able to register a callback whenever
1565 a read operation has completed. To be of any use we want to be able to
1566 call separate Perl subroutines for each file that is opened. As it
1567 stands, the error handler example above would not be adequate as it
1568 allows only a single callback to be defined at any time. What we
1569 require is a means of storing the mapping between the opened file and
1570 the Perl subroutine we want to be called for that file.
1572 Say the i/o library has a function C<asynch_read> which associates a C
1573 function C<ProcessRead> with a file handle C<fh>--this assumes that it
1574 has also provided some routine to open the file and so obtain the file
1577 asynch_read(fh, ProcessRead)
1579 This may expect the C I<ProcessRead> function of this form
1582 ProcessRead(fh, buffer)
1589 To provide a Perl interface to this library we need to be able to map
1590 between the C<fh> parameter and the Perl subroutine we want called. A
1591 hash is a convenient mechanism for storing this mapping. The code
1592 below shows a possible implementation
1594 static HV * Mapping = (HV*)NULL;
1597 asynch_read(fh, callback)
1601 /* If the hash doesn't already exist, create it */
1602 if (Mapping == (HV*)NULL)
1605 /* Save the fh -> callback mapping */
1606 hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
1608 /* Register with the C Library */
1609 asynch_read(fh, asynch_read_if);
1611 and C<asynch_read_if> could look like this
1614 asynch_read_if(fh, buffer)
1621 /* Get the callback associated with fh */
1622 sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
1623 if (sv == (SV**)NULL)
1624 croak("Internal error...\n");
1628 PUSHs(sv_2mortal(newSViv(fh)));
1629 PUSHs(sv_2mortal(newSVpv(buffer, 0)));
1632 /* Call the Perl sub */
1633 call_sv(*sv, G_DISCARD);
1636 For completeness, here is C<asynch_close>. This shows how to remove
1637 the entry from the hash C<Mapping>.
1643 /* Remove the entry from the hash */
1644 (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
1646 /* Now call the real asynch_close */
1649 So the Perl interface would look like this
1653 my($handle, $buffer) = @_;
1656 # Register the Perl callback
1657 asynch_read($fh, \&callback1);
1661 The mapping between the C callback and Perl is stored in the global
1662 hash C<Mapping> this time. Using a hash has the distinct advantage that
1663 it allows an unlimited number of callbacks to be registered.
1665 What if the interface provided by the C callback doesn't contain a
1666 parameter which allows the file handle to Perl subroutine mapping? Say
1667 in the asynchronous i/o package, the callback function gets passed only
1668 the C<buffer> parameter like this
1677 Without the file handle there is no straightforward way to map from the
1678 C callback to the Perl subroutine.
1680 In this case a possible way around this problem is to predefine a
1681 series of C functions to act as the interface to Perl, thus
1684 #define NULL_HANDLE -1
1685 typedef void (*FnMap)();
1697 static struct MapStruct Map [MAX_CB] =
1699 { fn1, NULL, NULL_HANDLE },
1700 { fn2, NULL, NULL_HANDLE },
1701 { fn3, NULL, NULL_HANDLE }
1712 XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
1715 /* Call the Perl sub */
1716 call_sv(Map[index].PerlSub, G_DISCARD);
1741 array_asynch_read(fh, callback)
1746 int null_index = MAX_CB;
1748 /* Find the same handle or an empty entry */
1749 for (index = 0; index < MAX_CB; ++index)
1751 if (Map[index].Handle == fh)
1754 if (Map[index].Handle == NULL_HANDLE)
1758 if (index == MAX_CB && null_index == MAX_CB)
1759 croak ("Too many callback functions registered\n");
1761 if (index == MAX_CB)
1764 /* Save the file handle */
1765 Map[index].Handle = fh;
1767 /* Remember the Perl sub */
1768 if (Map[index].PerlSub == (SV*)NULL)
1769 Map[index].PerlSub = newSVsv(callback);
1771 SvSetSV(Map[index].PerlSub, callback);
1773 asynch_read(fh, Map[index].Function);
1776 array_asynch_close(fh)
1781 /* Find the file handle */
1782 for (index = 0; index < MAX_CB; ++ index)
1783 if (Map[index].Handle == fh)
1786 if (index == MAX_CB)
1787 croak ("could not close fh %d\n", fh);
1789 Map[index].Handle = NULL_HANDLE;
1790 SvREFCNT_dec(Map[index].PerlSub);
1791 Map[index].PerlSub = (SV*)NULL;
1795 In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to
1796 remember the Perl subroutine to be called. Each of the functions holds
1797 a separate hard-wired index which is used in the function C<Pcb> to
1798 access the C<Map> array and actually call the Perl subroutine.
1800 There are some obvious disadvantages with this technique.
1802 Firstly, the code is considerably more complex than with the previous
1805 Secondly, there is a hard-wired limit (in this case 3) to the number of
1806 callbacks that can exist simultaneously. The only way to increase the
1807 limit is by modifying the code to add more functions and then
1808 recompiling. None the less, as long as the number of functions is
1809 chosen with some care, it is still a workable solution and in some
1810 cases is the only one available.
1812 To summarize, here are a number of possible methods for you to consider
1813 for storing the mapping between C and the Perl callback
1817 =item 1. Ignore the problem - Allow only 1 callback
1819 For a lot of situations, like interfacing to an error handler, this may
1820 be a perfectly adequate solution.
1822 =item 2. Create a sequence of callbacks - hard wired limit
1824 If it is impossible to tell from the parameters passed back from the C
1825 callback what the context is, then you may need to create a sequence of C
1826 callback interface functions, and store pointers to each in an array.
1828 =item 3. Use a parameter to map to the Perl callback
1830 A hash is an ideal mechanism to store the mapping between C and Perl.
1835 =head2 Alternate Stack Manipulation
1838 Although I have made use of only the C<POP*> macros to access values
1839 returned from Perl subroutines, it is also possible to bypass these
1840 macros and read the stack using the C<ST> macro (See L<perlxs> for a
1841 full description of the C<ST> macro).
1843 Most of the time the C<POP*> macros should be adequate; the main
1844 problem with them is that they force you to process the returned values
1845 in sequence. This may not be the most suitable way to process the
1846 values in some cases. What we want is to be able to access the stack in
1847 a random order. The C<ST> macro as used when coding an XSUB is ideal
1850 The code below is the example given in the section L</Returning a List
1851 of Values> recoded to use C<ST> instead of C<POP*>.
1854 call_AddSubtract2(a, b)
1867 PUSHs(sv_2mortal(newSViv(a)));
1868 PUSHs(sv_2mortal(newSViv(b)));
1871 count = call_pv("AddSubtract", G_LIST);
1875 ax = (SP - PL_stack_base) + 1;
1878 croak("Big trouble\n");
1880 printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
1881 printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));
1894 Notice that it was necessary to define the variable C<ax>. This is
1895 because the C<ST> macro expects it to exist. If we were in an XSUB it
1896 would not be necessary to define C<ax> as it is already defined for
1905 ax = (SP - PL_stack_base) + 1;
1907 sets the stack up so that we can use the C<ST> macro.
1911 Unlike the original coding of this example, the returned
1912 values are not accessed in reverse order. So C<ST(0)> refers to the
1913 first value returned by the Perl subroutine and C<ST(count-1)>
1918 =head2 Creating and Calling an Anonymous Subroutine in C
1920 As we've already shown, C<call_sv> can be used to invoke an
1921 anonymous subroutine. However, our example showed a Perl script
1922 invoking an XSUB to perform this operation. Let's see how it can be
1923 done inside our C code:
1929 print 'You will not find me cluttering any namespace!'
1934 call_sv(cvrv, G_VOID|G_NOARGS);
1936 C<eval_pv> is used to compile the anonymous subroutine, which
1937 will be the return value as well (read more about C<eval_pv> in
1938 L<perlapi/eval_pv>). Once this code reference is in hand, it
1939 can be mixed in with all the previous examples we've shown.
1941 =head1 LIGHTWEIGHT CALLBACKS
1943 Sometimes you need to invoke the same subroutine repeatedly.
1944 This usually happens with a function that acts on a list of
1945 values, such as Perl's built-in sort(). You can pass a
1946 comparison function to sort(), which will then be invoked
1947 for every pair of values that needs to be compared. The first()
1948 and reduce() functions from L<List::Util> follow a similar
1951 In this case it is possible to speed up the routine (often
1952 quite substantially) by using the lightweight callback API.
1953 The idea is that the calling context only needs to be
1954 created and destroyed once, and the sub can be called
1955 arbitrarily many times in between.
1957 It is usual to pass parameters using global variables (typically
1958 $_ for one parameter, or $a and $b for two parameters) rather
1959 than via @_. (It is possible to use the @_ mechanism if you know
1960 what you're doing, though there is as yet no supported API for
1961 it. It's also inherently slower.)
1963 The pattern of macro calls is like this:
1965 dMULTICALL; /* Declare local variables */
1966 U8 gimme = G_SCALAR; /* context of the call: G_SCALAR,
1967 * G_LIST, or G_VOID */
1969 PUSH_MULTICALL(cv); /* Set up the context for calling cv,
1970 and set local vars appropriately */
1973 /* set the value(s) af your parameter variables */
1974 MULTICALL; /* Make the actual call */
1977 POP_MULTICALL; /* Tear down the calling context */
1979 For some concrete examples, see the implementation of the
1980 first() and reduce() functions of List::Util 1.18. There you
1981 will also find a header file that emulates the multicall API
1982 on older versions of perl.
1986 L<perlxs>, L<perlguts>, L<perlembed>
1992 Special thanks to the following people who assisted in the creation of
1995 Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
2000 Last updated for perl 5.23.1.