1PERLCALL(1) Perl Programmers Reference Guide PERLCALL(1)
2
6 perlcall - Perl calling conventions from C
7
9 The purpose of this document is to show you how to call Perl
10 subroutines directly from C, i.e., how to write callbacks.
11 Apart from discussing the C interface provided by Perl for writing
13 callbacks the document uses a series of examples to show how the
14 interface actually works in practice. In addition some techniques for
15 coding callbacks are covered.
16 Examples where callbacks are necessary include
18 • An Error Handler
20 You have created an XSUB interface to an application's C API.
22 A fairly common feature in applications is to allow you to define
24 a C function that will be called whenever something nasty occurs.
25 What we would like is to be able to specify a Perl subroutine that
26 will be called instead.
27 • An Event-Driven Program
29 The classic example of where callbacks are used is when writing an
31 event driven program, such as for an X11 application. In this
32 case you register functions to be called whenever specific events
33 occur, e.g., a mouse button is pressed, the cursor moves into a
34 window or a menu item is selected.
35 Although the techniques described here are applicable when embedding
37 Perl in a C program, this is not the primary goal of this document.
38 There are other details that must be considered and are specific to
39 embedding Perl. For details on embedding Perl in C refer to perlembed.
40 Before you launch yourself head first into the rest of this document,
42 it would be a good idea to have read the following two
43 documents--perlxs and perlguts.
44
46 Although this stuff is easier to explain using examples, you first need
47 be aware of a few important definitions.
48 Perl has a number of C functions that allow you to call Perl
50 subroutines. They are
51 I32 call_sv(SV* sv, I32 flags);
53 I32 call_pv(char *subname, I32 flags);
54 I32 call_method(char *methname, I32 flags);
55 I32 call_argv(char *subname, I32 flags, char **argv);
56 The key function is call_sv. All the other functions are fairly simple
58 wrappers which make it easier to call Perl subroutines in special
59 cases. At the end of the day they will all call call_sv to invoke the
60 Perl subroutine.
61 All the call_* functions have a "flags" parameter which is used to pass
63 a bit mask of options to Perl. This bit mask operates identically for
64 each of the functions. The settings available in the bit mask are
65 discussed in "FLAG VALUES".
66 Each of the functions will now be discussed in turn.
68 call_sv
70 call_sv takes two parameters. The first, "sv", is an SV*. This
71 allows you to specify the Perl subroutine to be called either as a
72 C string (which has first been converted to an SV) or a reference
73 to a subroutine. The section, "Using call_sv", shows how you can
74 make use of call_sv.
75 call_pv
77 The function, call_pv, is similar to call_sv except it expects its
78 first parameter to be a C char* which identifies the Perl
79 subroutine you want to call, e.g., "call_pv("fred", 0)". If the
80 subroutine you want to call is in another package, just include
81 the package name in the string, e.g., "pkg::fred".
82 call_method
84 The function call_method is used to call a method from a Perl
85 class. The parameter "methname" corresponds to the name of the
86 method to be called. Note that the class that the method belongs
87 to is passed on the Perl stack rather than in the parameter list.
88 This class can be either the name of the class (for a static
89 method) or a reference to an object (for a virtual method). See
90 perlobj for more information on static and virtual methods and
91 "Using call_method" for an example of using call_method.
92 call_argv
94 call_argv calls the Perl subroutine specified by the C string
95 stored in the "subname" parameter. It also takes the usual "flags"
96 parameter. The final parameter, "argv", consists of a NULL-
97 terminated list of C strings to be passed as parameters to the
98 Perl subroutine. See "Using call_argv".
99 All the functions return an integer. This is a count of the number of
101 items returned by the Perl subroutine. The actual items returned by the
102 subroutine are stored on the Perl stack.
103 As a general rule you should always check the return value from these
105 functions. Even if you are expecting only a particular number of
106 values to be returned from the Perl subroutine, there is nothing to
107 stop someone from doing something unexpected--don't say you haven't
108 been warned.
109
111 The "flags" parameter in all the call_* functions is one of G_VOID,
112 G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together
113 with a bit mask of any combination of the other G_* symbols defined
114 below.
115 G_VOID
117 Calls the Perl subroutine in a void context.
118 This flag has 2 effects:
120 1. It indicates to the subroutine being called that it is executing
122 in a void context (if it executes wantarray the result will be the
123 undefined value).
124 2. It ensures that nothing is actually returned from the subroutine.
126 The value returned by the call_* function indicates how many items have
128 been returned by the Perl subroutine--in this case it will be 0.
129 G_SCALAR
131 Calls the Perl subroutine in a scalar context. This is the default
132 context flag setting for all the call_* functions.
133 This flag has 2 effects:
135 1. It indicates to the subroutine being called that it is executing
137 in a scalar context (if it executes wantarray the result will be
138 false).
139 2. It ensures that only a scalar is actually returned from the
141 subroutine. The subroutine can, of course, ignore the wantarray
142 and return a list anyway. If so, then only the last element of the
143 list will be returned.
144 The value returned by the call_* function indicates how many items have
146 been returned by the Perl subroutine - in this case it will be either 0
147 or 1.
148 If 0, then you have specified the G_DISCARD flag.
150 If 1, then the item actually returned by the Perl subroutine will be
152 stored on the Perl stack - the section "Returning a Scalar" shows how
153 to access this value on the stack. Remember that regardless of how
154 many items the Perl subroutine returns, only the last one will be
155 accessible from the stack - think of the case where only one value is
156 returned as being a list with only one element. Any other items that
157 were returned will not exist by the time control returns from the
158 call_* function. The section "Returning a List in Scalar Context"
159 shows an example of this behavior.
160 G_ARRAY
162 Calls the Perl subroutine in a list context.
163 As with G_SCALAR, this flag has 2 effects:
165 1. It indicates to the subroutine being called that it is executing
167 in a list context (if it executes wantarray the result will be
168 true).
169 2. It ensures that all items returned from the subroutine will be
171 accessible when control returns from the call_* function.
172 The value returned by the call_* function indicates how many items have
174 been returned by the Perl subroutine.
175 If 0, then you have specified the G_DISCARD flag.
177 If not 0, then it will be a count of the number of items returned by
179 the subroutine. These items will be stored on the Perl stack. The
180 section "Returning a List of Values" gives an example of using the
181 G_ARRAY flag and the mechanics of accessing the returned items from the
182 Perl stack.
183 G_DISCARD
185 By default, the call_* functions place the items returned from by the
186 Perl subroutine on the stack. If you are not interested in these
187 items, then setting this flag will make Perl get rid of them
188 automatically for you. Note that it is still possible to indicate a
189 context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
190 If you do not set this flag then it is very important that you make
192 sure that any temporaries (i.e., parameters passed to the Perl
193 subroutine and values returned from the subroutine) are disposed of
194 yourself. The section "Returning a Scalar" gives details of how to
195 dispose of these temporaries explicitly and the section "Using Perl to
196 Dispose of Temporaries" discusses the specific circumstances where you
197 can ignore the problem and let Perl deal with it for you.
198 G_NOARGS
200 Whenever a Perl subroutine is called using one of the call_* functions,
201 it is assumed by default that parameters are to be passed to the
202 subroutine. If you are not passing any parameters to the Perl
203 subroutine, you can save a bit of time by setting this flag. It has
204 the effect of not creating the @_ array for the Perl subroutine.
205 Although the functionality provided by this flag may seem
207 straightforward, it should be used only if there is a good reason to do
208 so. The reason for being cautious is that, even if you have specified
209 the G_NOARGS flag, it is still possible for the Perl subroutine that
210 has been called to think that you have passed it parameters.
211 In fact, what can happen is that the Perl subroutine you have called
213 can access the @_ array from a previous Perl subroutine. This will
214 occur when the code that is executing the call_* function has itself
215 been called from another Perl subroutine. The code below illustrates
216 this
217 sub fred
219 { print "@_\n" }
220 sub joe
222 { &fred }
223 &joe(1,2,3);
225 This will print
227 1 2 3
229 What has happened is that "fred" accesses the @_ array which belongs to
231 "joe".
232 G_EVAL
234 It is possible for the Perl subroutine you are calling to terminate
235 abnormally, e.g., by calling die explicitly or by not actually
236 existing. By default, when either of these events occurs, the process
237 will terminate immediately. If you want to trap this type of event,
238 specify the G_EVAL flag. It will put an eval { } around the subroutine
239 call.
240 Whenever control returns from the call_* function you need to check the
242 $@ variable as you would in a normal Perl script.
243 The value returned from the call_* function is dependent on what other
245 flags have been specified and whether an error has occurred. Here are
246 all the different cases that can occur:
247 • If the call_* function returns normally, then the value returned
249 is as specified in the previous sections.
250 • If G_DISCARD is specified, the return value will always be 0.
252 • If G_ARRAY is specified and an error has occurred, the return
254 value will always be 0.
255 • If G_SCALAR is specified and an error has occurred, the return
257 value will be 1 and the value on the top of the stack will be
258 undef. This means that if you have already detected the error by
259 checking $@ and you want the program to continue, you must
260 remember to pop the undef from the stack.
261 See "Using G_EVAL" for details on using G_EVAL.
263 G_KEEPERR
265 Using the G_EVAL flag described above will always set $@: clearing it
266 if there was no error, and setting it to describe the error if there
267 was an error in the called code. This is what you want if your
268 intention is to handle possible errors, but sometimes you just want to
269 trap errors and stop them interfering with the rest of the program.
270 This scenario will mostly be applicable to code that is meant to be
272 called from within destructors, asynchronous callbacks, and signal
273 handlers. In such situations, where the code being called has little
274 relation to the surrounding dynamic context, the main program needs to
275 be insulated from errors in the called code, even if they can't be
276 handled intelligently. It may also be useful to do this with code for
277 "__DIE__" or "__WARN__" hooks, and "tie" functions.
278 The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
280 call_* functions that are used to implement such code, or with
281 "eval_sv". This flag has no effect on the "call_*" functions when
282 G_EVAL is not used.
283 When G_KEEPERR is used, any error in the called code will terminate the
285 call as usual, and the error will not propagate beyond the call (as
286 usual for G_EVAL), but it will not go into $@. Instead the error will
287 be converted into a warning, prefixed with the string "\t(in cleanup)".
288 This can be disabled using "no warnings 'misc'". If there is no error,
289 $@ will not be cleared.
290 Note that the G_KEEPERR flag does not propagate into inner evals; these
292 may still set $@.
293 The G_KEEPERR flag was introduced in Perl version 5.002.
295 See "Using G_KEEPERR" for an example of a situation that warrants the
297 use of this flag.
298 Determining the Context
300 As mentioned above, you can determine the context of the currently
301 executing subroutine in Perl with wantarray. The equivalent test can
302 be made in C by using the "GIMME_V" macro, which returns "G_ARRAY" if
303 you have been called in a list context, "G_SCALAR" if in a scalar
304 context, or "G_VOID" if in a void context (i.e., the return value will
305 not be used). An older version of this macro is called "GIMME"; in a
306 void context it returns "G_SCALAR" instead of "G_VOID". An example of
307 using the "GIMME_V" macro is shown in section "Using GIMME_V".
308
310 Enough of the definition talk! Let's have a few examples.
311 Perl provides many macros to assist in accessing the Perl stack.
313 Wherever possible, these macros should always be used when interfacing
314 to Perl internals. We hope this should make the code less vulnerable
315 to any changes made to Perl in the future.
316 Another point worth noting is that in the first series of examples I
318 have made use of only the call_pv function. This has been done to keep
319 the code simpler and ease you into the topic. Wherever possible, if
320 the choice is between using call_pv and call_sv, you should always try
321 to use call_sv. See "Using call_sv" for details.
322 No Parameters, Nothing Returned
324 This first trivial example will call a Perl subroutine, PrintUID, to
325 print out the UID of the process.
326 sub PrintUID
328 {
329 print "UID is $<\n";
330 }
331 and here is a C function to call it
333 static void
335 call_PrintUID()
336 {
337 dSP;
338 PUSHMARK(SP);
340 call_pv("PrintUID", G_DISCARD|G_NOARGS);
341 }
342 Simple, eh?
344 A few points to note about this example:
346 1. Ignore "dSP" and "PUSHMARK(SP)" for now. They will be discussed in
348 the next example.
349 2. We aren't passing any parameters to PrintUID so G_NOARGS can be
351 specified.
352 3. We aren't interested in anything returned from PrintUID, so
354 G_DISCARD is specified. Even if PrintUID was changed to return
355 some value(s), having specified G_DISCARD will mean that they will
356 be wiped by the time control returns from call_pv.
357 4. As call_pv is being used, the Perl subroutine is specified as a C
359 string. In this case the subroutine name has been 'hard-wired'
360 into the code.
361 5. Because we specified G_DISCARD, it is not necessary to check the
363 value returned from call_pv. It will always be 0.
364 Passing Parameters
366 Now let's make a slightly more complex example. This time we want to
367 call a Perl subroutine, "LeftString", which will take 2 parameters--a
368 string ($s) and an integer ($n). The subroutine will simply print the
369 first $n characters of the string.
370 So the Perl subroutine would look like this:
372 sub LeftString
374 {
375 my($s, $n) = @_;
376 print substr($s, 0, $n), "\n";
377 }
378 The C function required to call LeftString would look like this:
380 static void
382 call_LeftString(a, b)
383 char * a;
384 int b;
385 {
386 dSP;
387 ENTER;
389 SAVETMPS;
390 PUSHMARK(SP);
392 EXTEND(SP, 2);
393 PUSHs(sv_2mortal(newSVpv(a, 0)));
394 PUSHs(sv_2mortal(newSViv(b)));
395 PUTBACK;
396 call_pv("LeftString", G_DISCARD);
398 FREETMPS;
400 LEAVE;
401 }
402 Here are a few notes on the C function call_LeftString.
404 1. Parameters are passed to the Perl subroutine using the Perl stack.
406 This is the purpose of the code beginning with the line "dSP" and
407 ending with the line "PUTBACK". The "dSP" declares a local copy
408 of the stack pointer. This local copy should always be accessed
409 as "SP".
410 2. If you are going to put something onto the Perl stack, you need to
412 know where to put it. This is the purpose of the macro "dSP"--it
413 declares and initializes a local copy of the Perl stack pointer.
414 All the other macros which will be used in this example require
416 you to have used this macro.
417 The exception to this rule is if you are calling a Perl subroutine
419 directly from an XSUB function. In this case it is not necessary
420 to use the "dSP" macro explicitly--it will be declared for you
421 automatically.
422 3. Any parameters to be pushed onto the stack should be bracketed by
424 the "PUSHMARK" and "PUTBACK" macros. The purpose of these two
425 macros, in this context, is to count the number of parameters you
426 are pushing automatically. Then whenever Perl is creating the @_
427 array for the subroutine, it knows how big to make it.
428 The "PUSHMARK" macro tells Perl to make a mental note of the
430 current stack pointer. Even if you aren't passing any parameters
431 (like the example shown in the section "No Parameters, Nothing
432 Returned") you must still call the "PUSHMARK" macro before you can
433 call any of the call_* functions--Perl still needs to know that
434 there are no parameters.
435 The "PUTBACK" macro sets the global copy of the stack pointer to
437 be the same as our local copy. If we didn't do this, call_pv
438 wouldn't know where the two parameters we pushed were--remember
439 that up to now all the stack pointer manipulation we have done is
440 with our local copy, not the global copy.
441 4. Next, we come to EXTEND and PUSHs. This is where the parameters
443 actually get pushed onto the stack. In this case we are pushing a
444 string and an integer.
445 Alternatively you can use the XPUSHs() macro, which combines a
447 "EXTEND(SP, 1)" and "PUSHs()". This is less efficient if you're
448 pushing multiple values.
449 See "XSUBs and the Argument Stack" in perlguts for details on how
451 the PUSH macros work.
452 5. Because we created temporary values (by means of sv_2mortal()
454 calls) we will have to tidy up the Perl stack and dispose of
455 mortal SVs.
456 This is the purpose of
458 ENTER;
460 SAVETMPS;
461 at the start of the function, and
463 FREETMPS;
465 LEAVE;
466 at the end. The "ENTER"/"SAVETMPS" pair creates a boundary for any
468 temporaries we create. This means that the temporaries we get rid
469 of will be limited to those which were created after these calls.
470 The "FREETMPS"/"LEAVE" pair will get rid of any values returned by
472 the Perl subroutine (see next example), plus it will also dump the
473 mortal SVs we have created. Having "ENTER"/"SAVETMPS" at the
474 beginning of the code makes sure that no other mortals are
475 destroyed.
476 Think of these macros as working a bit like "{" and "}" in Perl to
478 limit the scope of local variables.
479 See the section "Using Perl to Dispose of Temporaries" for details
481 of an alternative to using these macros.
482 6. Finally, LeftString can now be called via the call_pv function.
484 The only flag specified this time is G_DISCARD. Because we are
485 passing 2 parameters to the Perl subroutine this time, we have not
486 specified G_NOARGS.
487 Returning a Scalar
489 Now for an example of dealing with the items returned from a Perl
490 subroutine.
491 Here is a Perl subroutine, Adder, that takes 2 integer parameters and
493 simply returns their sum.
494 sub Adder
496 {
497 my($a, $b) = @_;
498 $a + $b;
499 }
500 Because we are now concerned with the return value from Adder, the C
502 function required to call it is now a bit more complex.
503 static void
505 call_Adder(a, b)
506 int a;
507 int b;
508 {
509 dSP;
510 int count;
511 ENTER;
513 SAVETMPS;
514 PUSHMARK(SP);
516 EXTEND(SP, 2);
517 PUSHs(sv_2mortal(newSViv(a)));
518 PUSHs(sv_2mortal(newSViv(b)));
519 PUTBACK;
520 count = call_pv("Adder", G_SCALAR);
522 SPAGAIN;
524 if (count != 1)
526 croak("Big trouble\n");
527 printf ("The sum of %d and %d is %d\n", a, b, POPi);
529 PUTBACK;
531 FREETMPS;
532 LEAVE;
533 }
534 Points to note this time are
536 1. The only flag specified this time was G_SCALAR. That means that
538 the @_ array will be created and that the value returned by Adder
539 will still exist after the call to call_pv.
540 2. The purpose of the macro "SPAGAIN" is to refresh the local copy of
542 the stack pointer. This is necessary because it is possible that
543 the memory allocated to the Perl stack has been reallocated during
544 the call_pv call.
545 If you are making use of the Perl stack pointer in your code you
547 must always refresh the local copy using SPAGAIN whenever you make
548 use of the call_* functions or any other Perl internal function.
549 3. Although only a single value was expected to be returned from
551 Adder, it is still good practice to check the return code from
552 call_pv anyway.
553 Expecting a single value is not quite the same as knowing that
555 there will be one. If someone modified Adder to return a list and
556 we didn't check for that possibility and take appropriate action
557 the Perl stack would end up in an inconsistent state. That is
558 something you really don't want to happen ever.
559 4. The "POPi" macro is used here to pop the return value from the
561 stack. In this case we wanted an integer, so "POPi" was used.
562 Here is the complete list of POP macros available, along with the
564 types they return.
565 POPs SV
567 POPp pointer (PV)
568 POPpbytex pointer to bytes (PV)
569 POPn double (NV)
570 POPi integer (IV)
571 POPu unsigned integer (UV)
572 POPl long
573 POPul unsigned long
574 Since these macros have side-effects don't use them as arguments
576 to macros that may evaluate their argument several times, for
577 example:
578 /* Bad idea, don't do this */
580 STRLEN len;
581 const char *s = SvPV(POPs, len);
582 Instead, use a temporary:
584 STRLEN len;
586 SV *sv = POPs;
587 const char *s = SvPV(sv, len);
588 or a macro that guarantees it will evaluate its arguments only
590 once:
591 STRLEN len;
593 const char *s = SvPVx(POPs, len);
594 5. The final "PUTBACK" is used to leave the Perl stack in a
596 consistent state before exiting the function. This is necessary
597 because when we popped the return value from the stack with "POPi"
598 it updated only our local copy of the stack pointer. Remember,
599 "PUTBACK" sets the global stack pointer to be the same as our
600 local copy.
601 Returning a List of Values
603 Now, let's extend the previous example to return both the sum of the
604 parameters and the difference.
605 Here is the Perl subroutine
607 sub AddSubtract
609 {
610 my($a, $b) = @_;
611 ($a+$b, $a-$b);
612 }
613 and this is the C function
615 static void
617 call_AddSubtract(a, b)
618 int a;
619 int b;
620 {
621 dSP;
622 int count;
623 ENTER;
625 SAVETMPS;
626 PUSHMARK(SP);
628 EXTEND(SP, 2);
629 PUSHs(sv_2mortal(newSViv(a)));
630 PUSHs(sv_2mortal(newSViv(b)));
631 PUTBACK;
632 count = call_pv("AddSubtract", G_ARRAY);
634 SPAGAIN;
636 if (count != 2)
638 croak("Big trouble\n");
639 printf ("%d - %d = %d\n", a, b, POPi);
641 printf ("%d + %d = %d\n", a, b, POPi);
642 PUTBACK;
644 FREETMPS;
645 LEAVE;
646 }
647 If call_AddSubtract is called like this
649 call_AddSubtract(7, 4);
651 then here is the output
653 7 - 4 = 3
655 7 + 4 = 11
656 Notes
658 1. We wanted list context, so G_ARRAY was used.
660 2. Not surprisingly "POPi" is used twice this time because we were
662 retrieving 2 values from the stack. The important thing to note is
663 that when using the "POP*" macros they come off the stack in
664 reverse order.
665 Returning a List in Scalar Context
667 Say the Perl subroutine in the previous section was called in a scalar
668 context, like this
669 static void
671 call_AddSubScalar(a, b)
672 int a;
673 int b;
674 {
675 dSP;
676 int count;
677 int i;
678 ENTER;
680 SAVETMPS;
681 PUSHMARK(SP);
683 EXTEND(SP, 2);
684 PUSHs(sv_2mortal(newSViv(a)));
685 PUSHs(sv_2mortal(newSViv(b)));
686 PUTBACK;
687 count = call_pv("AddSubtract", G_SCALAR);
689 SPAGAIN;
691 printf ("Items Returned = %d\n", count);
693 for (i = 1; i <= count; ++i)
695 printf ("Value %d = %d\n", i, POPi);
696 PUTBACK;
698 FREETMPS;
699 LEAVE;
700 }
701 The other modification made is that call_AddSubScalar will print the
703 number of items returned from the Perl subroutine and their value (for
704 simplicity it assumes that they are integer). So if call_AddSubScalar
705 is called
706 call_AddSubScalar(7, 4);
708 then the output will be
710 Items Returned = 1
712 Value 1 = 3
713 In this case the main point to note is that only the last item in the
715 list is returned from the subroutine. AddSubtract actually made it back
716 to call_AddSubScalar.
717 Returning Data from Perl via the Parameter List
719 It is also possible to return values directly via the parameter
720 list--whether it is actually desirable to do it is another matter
721 entirely.
722 The Perl subroutine, Inc, below takes 2 parameters and increments each
724 directly.
725 sub Inc
727 {
728 ++ $_[0];
729 ++ $_[1];
730 }
731 and here is a C function to call it.
733 static void
735 call_Inc(a, b)
736 int a;
737 int b;
738 {
739 dSP;
740 int count;
741 SV * sva;
742 SV * svb;
743 ENTER;
745 SAVETMPS;
746 sva = sv_2mortal(newSViv(a));
748 svb = sv_2mortal(newSViv(b));
749 PUSHMARK(SP);
751 EXTEND(SP, 2);
752 PUSHs(sva);
753 PUSHs(svb);
754 PUTBACK;
755 count = call_pv("Inc", G_DISCARD);
757 if (count != 0)
759 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
760 count);
761 printf ("%d + 1 = %d\n", a, SvIV(sva));
763 printf ("%d + 1 = %d\n", b, SvIV(svb));
764 FREETMPS;
766 LEAVE;
767 }
768 To be able to access the two parameters that were pushed onto the stack
770 after they return from call_pv it is necessary to make a note of their
771 addresses--thus the two variables "sva" and "svb".
772 The reason this is necessary is that the area of the Perl stack which
774 held them will very likely have been overwritten by something else by
775 the time control returns from call_pv.
776 Using G_EVAL
778 Now an example using G_EVAL. Below is a Perl subroutine which computes
779 the difference of its 2 parameters. If this would result in a negative
780 result, the subroutine calls die.
781 sub Subtract
783 {
784 my ($a, $b) = @_;
785 die "death can be fatal\n" if $a < $b;
787 $a - $b;
789 }
790 and some C to call it
792 static void
794 call_Subtract(a, b)
795 int a;
796 int b;
797 {
798 dSP;
799 int count;
800 SV *err_tmp;
801 ENTER;
803 SAVETMPS;
804 PUSHMARK(SP);
806 EXTEND(SP, 2);
807 PUSHs(sv_2mortal(newSViv(a)));
808 PUSHs(sv_2mortal(newSViv(b)));
809 PUTBACK;
810 count = call_pv("Subtract", G_EVAL|G_SCALAR);
812 SPAGAIN;
814 /* Check the eval first */
816 err_tmp = ERRSV;
817 if (SvTRUE(err_tmp))
818 {
819 printf ("Uh oh - %s\n", SvPV_nolen(err_tmp));
820 POPs;
821 }
822 else
823 {
824 if (count != 1)
825 croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
826 count);
827 printf ("%d - %d = %d\n", a, b, POPi);
829 }
830 PUTBACK;
832 FREETMPS;
833 LEAVE;
834 }
835 If call_Subtract is called thus
837 call_Subtract(4, 5)
839 the following will be printed
841 Uh oh - death can be fatal
843 Notes
845 1. We want to be able to catch the die so we have used the G_EVAL
847 flag. Not specifying this flag would mean that the program would
848 terminate immediately at the die statement in the subroutine
849 Subtract.
850 2. The code
852 err_tmp = ERRSV;
854 if (SvTRUE(err_tmp))
855 {
856 printf ("Uh oh - %s\n", SvPV_nolen(err_tmp));
857 POPs;
858 }
859 is the direct equivalent of this bit of Perl
861 print "Uh oh - $@\n" if $@;
863 "PL_errgv" is a perl global of type "GV *" that points to the
865 symbol table entry containing the error. "ERRSV" therefore refers
866 to the C equivalent of $@. We use a local temporary, "err_tmp",
867 since "ERRSV" is a macro that calls a function, and
868 "SvTRUE(ERRSV)" would end up calling that function multiple times.
869 3. Note that the stack is popped using "POPs" in the block where
871 "SvTRUE(err_tmp)" is true. This is necessary because whenever a
872 call_* function invoked with G_EVAL|G_SCALAR returns an error, the
873 top of the stack holds the value undef. Because we want the
874 program to continue after detecting this error, it is essential
875 that the stack be tidied up by removing the undef.
876 Using G_KEEPERR
878 Consider this rather facetious example, where we have used an XS
879 version of the call_Subtract example above inside a destructor:
880 package Foo;
882 sub new { bless {}, $_[0] }
883 sub Subtract {
884 my($a,$b) = @_;
885 die "death can be fatal" if $a < $b;
886 $a - $b;
887 }
888 sub DESTROY { call_Subtract(5, 4); }
889 sub foo { die "foo dies"; }
890 package main;
892 {
893 my $foo = Foo->new;
894 eval { $foo->foo };
895 }
896 print "Saw: $@" if $@; # should be, but isn't
897 This example will fail to recognize that an error occurred inside the
899 "eval {}". Here's why: the call_Subtract code got executed while perl
900 was cleaning up temporaries when exiting the outer braced block, and
901 because call_Subtract is implemented with call_pv using the G_EVAL
902 flag, it promptly reset $@. This results in the failure of the
903 outermost test for $@, and thereby the failure of the error trap.
904 Appending the G_KEEPERR flag, so that the call_pv call in call_Subtract
906 reads:
907 count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
909 will preserve the error and restore reliable error handling.
911 Using call_sv
913 In all the previous examples I have 'hard-wired' the name of the Perl
914 subroutine to be called from C. Most of the time though, it is more
915 convenient to be able to specify the name of the Perl subroutine from
916 within the Perl script, and you'll want to use call_sv.
917 Consider the Perl code below
919 sub fred
921 {
922 print "Hello there\n";
923 }
924 CallSubPV("fred");
926 Here is a snippet of XSUB which defines CallSubPV.
928 void
930 CallSubPV(name)
931 char * name
932 CODE:
933 PUSHMARK(SP);
934 call_pv(name, G_DISCARD|G_NOARGS);
935 That is fine as far as it goes. The thing is, the Perl subroutine can
937 be specified as only a string, however, Perl allows references to
938 subroutines and anonymous subroutines. This is where call_sv is
939 useful.
940 The code below for CallSubSV is identical to CallSubPV except that the
942 "name" parameter is now defined as an SV* and we use call_sv instead of
943 call_pv.
944 void
946 CallSubSV(name)
947 SV * name
948 CODE:
949 PUSHMARK(SP);
950 call_sv(name, G_DISCARD|G_NOARGS);
951 Because we are using an SV to call fred the following can all be used:
953 CallSubSV("fred");
955 CallSubSV(\&fred);
956 $ref = \&fred;
957 CallSubSV($ref);
958 CallSubSV( sub { print "Hello there\n" } );
959 As you can see, call_sv gives you much greater flexibility in how you
961 can specify the Perl subroutine.
962 You should note that, if it is necessary to store the SV ("name" in the
964 example above) which corresponds to the Perl subroutine so that it can
965 be used later in the program, it not enough just to store a copy of the
966 pointer to the SV. Say the code above had been like this:
967 static SV * rememberSub;
969 void
971 SaveSub1(name)
972 SV * name
973 CODE:
974 rememberSub = name;
975 void
977 CallSavedSub1()
978 CODE:
979 PUSHMARK(SP);
980 call_sv(rememberSub, G_DISCARD|G_NOARGS);
981 The reason this is wrong is that, by the time you come to use the
983 pointer "rememberSub" in "CallSavedSub1", it may or may not still refer
984 to the Perl subroutine that was recorded in "SaveSub1". This is
985 particularly true for these cases:
986 SaveSub1(\&fred);
988 CallSavedSub1();
989 SaveSub1( sub { print "Hello there\n" } );
991 CallSavedSub1();
992 By the time each of the "SaveSub1" statements above has been executed,
994 the SV*s which corresponded to the parameters will no longer exist.
995 Expect an error message from Perl of the form
996 Can't use an undefined value as a subroutine reference at ...
998 for each of the "CallSavedSub1" lines.
1000 Similarly, with this code
1002 $ref = \&fred;
1004 SaveSub1($ref);
1005 $ref = 47;
1006 CallSavedSub1();
1007 you can expect one of these messages (which you actually get is
1009 dependent on the version of Perl you are using)
1010 Not a CODE reference at ...
1012 Undefined subroutine &main::47 called ...
1013 The variable $ref may have referred to the subroutine "fred" whenever
1015 the call to "SaveSub1" was made but by the time "CallSavedSub1" gets
1016 called it now holds the number 47. Because we saved only a pointer to
1017 the original SV in "SaveSub1", any changes to $ref will be tracked by
1018 the pointer "rememberSub". This means that whenever "CallSavedSub1"
1019 gets called, it will attempt to execute the code which is referenced by
1020 the SV* "rememberSub". In this case though, it now refers to the
1021 integer 47, so expect Perl to complain loudly.
1022 A similar but more subtle problem is illustrated with this code:
1024 $ref = \&fred;
1026 SaveSub1($ref);
1027 $ref = \&joe;
1028 CallSavedSub1();
1029 This time whenever "CallSavedSub1" gets called it will execute the Perl
1031 subroutine "joe" (assuming it exists) rather than "fred" as was
1032 originally requested in the call to "SaveSub1".
1033 To get around these problems it is necessary to take a full copy of the
1035 SV. The code below shows "SaveSub2" modified to do that.
1036 /* this isn't thread-safe */
1038 static SV * keepSub = (SV*)NULL;
1039 void
1041 SaveSub2(name)
1042 SV * name
1043 CODE:
1044 /* Take a copy of the callback */
1045 if (keepSub == (SV*)NULL)
1046 /* First time, so create a new SV */
1047 keepSub = newSVsv(name);
1048 else
1049 /* Been here before, so overwrite */
1050 SvSetSV(keepSub, name);
1051 void
1053 CallSavedSub2()
1054 CODE:
1055 PUSHMARK(SP);
1056 call_sv(keepSub, G_DISCARD|G_NOARGS);
1057 To avoid creating a new SV every time "SaveSub2" is called, the
1059 function first checks to see if it has been called before. If not,
1060 then space for a new SV is allocated and the reference to the Perl
1061 subroutine "name" is copied to the variable "keepSub" in one operation
1062 using "newSVsv". Thereafter, whenever "SaveSub2" is called, the
1063 existing SV, "keepSub", is overwritten with the new value using
1064 "SvSetSV".
1065 Note: using a static or global variable to store the SV isn't thread-
1067 safe. You can either use the "MY_CXT" mechanism documented in "Safely
1068 Storing Static Data in XS" in perlxs which is fast, or store the values
1069 in perl global variables, using get_sv(), which is much slower.
1070 Using call_argv
1072 Here is a Perl subroutine which prints whatever parameters are passed
1073 to it.
1074 sub PrintList
1076 {
1077 my(@list) = @_;
1078 foreach (@list) { print "$_\n" }
1080 }
1081 And here is an example of call_argv which will call PrintList.
1083 static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
1085 static void
1087 call_PrintList()
1088 {
1089 call_argv("PrintList", G_DISCARD, words);
1090 }
1091 Note that it is not necessary to call "PUSHMARK" in this instance.
1093 This is because call_argv will do it for you.
1094 Using call_method
1096 Consider the following Perl code:
1097 {
1099 package Mine;
1100 sub new
1102 {
1103 my($type) = shift;
1104 bless [@_]
1105 }
1106 sub Display
1108 {
1109 my ($self, $index) = @_;
1110 print "$index: $$self[$index]\n";
1111 }
1112 sub PrintID
1114 {
1115 my($class) = @_;
1116 print "This is Class $class version 1.0\n";
1117 }
1118 }
1119 It implements just a very simple class to manage an array. Apart from
1121 the constructor, "new", it declares methods, one static and one
1122 virtual. The static method, "PrintID", prints out simply the class name
1123 and a version number. The virtual method, "Display", prints out a
1124 single element of the array. Here is an all-Perl example of using it.
1125 $a = Mine->new('red', 'green', 'blue');
1127 $a->Display(1);
1128 Mine->PrintID;
1129 will print
1131 1: green
1133 This is Class Mine version 1.0
1134 Calling a Perl method from C is fairly straightforward. The following
1136 things are required:
1137 • A reference to the object for a virtual method or the name of the
1139 class for a static method
1140 • The name of the method
1142 • Any other parameters specific to the method
1144 Here is a simple XSUB which illustrates the mechanics of calling both
1146 the "PrintID" and "Display" methods from C.
1147 void
1149 call_Method(ref, method, index)
1150 SV * ref
1151 char * method
1152 int index
1153 CODE:
1154 PUSHMARK(SP);
1155 EXTEND(SP, 2);
1156 PUSHs(ref);
1157 PUSHs(sv_2mortal(newSViv(index)));
1158 PUTBACK;
1159 call_method(method, G_DISCARD);
1161 void
1163 call_PrintID(class, method)
1164 char * class
1165 char * method
1166 CODE:
1167 PUSHMARK(SP);
1168 XPUSHs(sv_2mortal(newSVpv(class, 0)));
1169 PUTBACK;
1170 call_method(method, G_DISCARD);
1172 So the methods "PrintID" and "Display" can be invoked like this:
1174 $a = Mine->new('red', 'green', 'blue');
1176 call_Method($a, 'Display', 1);
1177 call_PrintID('Mine', 'PrintID');
1178 The only thing to note is that, in both the static and virtual methods,
1180 the method name is not passed via the stack--it is used as the first
1181 parameter to call_method.
1182 Using GIMME_V
1184 Here is a trivial XSUB which prints the context in which it is
1185 currently executing.
1186 void
1188 PrintContext()
1189 CODE:
1190 U8 gimme = GIMME_V;
1191 if (gimme == G_VOID)
1192 printf ("Context is Void\n");
1193 else if (gimme == G_SCALAR)
1194 printf ("Context is Scalar\n");
1195 else
1196 printf ("Context is Array\n");
1197 And here is some Perl to test it.
1199 PrintContext;
1201 $a = PrintContext;
1202 @a = PrintContext;
1203 The output from that will be
1205 Context is Void
1207 Context is Scalar
1208 Context is Array
1209 Using Perl to Dispose of Temporaries
1211 In the examples given to date, any temporaries created in the callback
1212 (i.e., parameters passed on the stack to the call_* function or values
1213 returned via the stack) have been freed by one of these methods:
1214 • Specifying the G_DISCARD flag with call_*
1216 • Explicitly using the "ENTER"/"SAVETMPS"--"FREETMPS"/"LEAVE"
1218 pairing
1219 There is another method which can be used, namely letting Perl do it
1221 for you automatically whenever it regains control after the callback
1222 has terminated. This is done by simply not using the
1223 ENTER;
1225 SAVETMPS;
1226 ...
1227 FREETMPS;
1228 LEAVE;
1229 sequence in the callback (and not, of course, specifying the G_DISCARD
1231 flag).
1232 If you are going to use this method you have to be aware of a possible
1234 memory leak which can arise under very specific circumstances. To
1235 explain these circumstances you need to know a bit about the flow of
1236 control between Perl and the callback routine.
1237 The examples given at the start of the document (an error handler and
1239 an event driven program) are typical of the two main sorts of flow
1240 control that you are likely to encounter with callbacks. There is a
1241 very important distinction between them, so pay attention.
1242 In the first example, an error handler, the flow of control could be as
1244 follows. You have created an interface to an external library.
1245 Control can reach the external library like this
1246 perl --> XSUB --> external library
1248 Whilst control is in the library, an error condition occurs. You have
1250 previously set up a Perl callback to handle this situation, so it will
1251 get executed. Once the callback has finished, control will drop back to
1252 Perl again. Here is what the flow of control will be like in that
1253 situation
1254 perl --> XSUB --> external library
1256 ...
1257 error occurs
1258 ...
1259 external library --> call_* --> perl
1260 |
1261 perl <-- XSUB <-- external library <-- call_* <----+
1262 After processing of the error using call_* is completed, control
1264 reverts back to Perl more or less immediately.
1265 In the diagram, the further right you go the more deeply nested the
1267 scope is. It is only when control is back with perl on the extreme
1268 left of the diagram that you will have dropped back to the enclosing
1269 scope and any temporaries you have left hanging around will be freed.
1270 In the second example, an event driven program, the flow of control
1272 will be more like this
1273 perl --> XSUB --> event handler
1275 ...
1276 event handler --> call_* --> perl
1277 |
1278 event handler <-- call_* <----+
1279 ...
1280 event handler --> call_* --> perl
1281 |
1282 event handler <-- call_* <----+
1283 ...
1284 event handler --> call_* --> perl
1285 |
1286 event handler <-- call_* <----+
1287 In this case the flow of control can consist of only the repeated
1289 sequence
1290 event handler --> call_* --> perl
1292 for practically the complete duration of the program. This means that
1294 control may never drop back to the surrounding scope in Perl at the
1295 extreme left.
1296 So what is the big problem? Well, if you are expecting Perl to tidy up
1298 those temporaries for you, you might be in for a long wait. For Perl
1299 to dispose of your temporaries, control must drop back to the enclosing
1300 scope at some stage. In the event driven scenario that may never
1301 happen. This means that, as time goes on, your program will create
1302 more and more temporaries, none of which will ever be freed. As each of
1303 these temporaries consumes some memory your program will eventually
1304 consume all the available memory in your system--kapow!
1305 So here is the bottom line--if you are sure that control will revert
1307 back to the enclosing Perl scope fairly quickly after the end of your
1308 callback, then it isn't absolutely necessary to dispose explicitly of
1309 any temporaries you may have created. Mind you, if you are at all
1310 uncertain about what to do, it doesn't do any harm to tidy up anyway.
1311 Strategies for Storing Callback Context Information
1313 Potentially one of the trickiest problems to overcome when designing a
1314 callback interface can be figuring out how to store the mapping between
1315 the C callback function and the Perl equivalent.
1316 To help understand why this can be a real problem first consider how a
1318 callback is set up in an all C environment. Typically a C API will
1319 provide a function to register a callback. This will expect a pointer
1320 to a function as one of its parameters. Below is a call to a
1321 hypothetical function "register_fatal" which registers the C function
1322 to get called when a fatal error occurs.
1323 register_fatal(cb1);
1325 The single parameter "cb1" is a pointer to a function, so you must have
1327 defined "cb1" in your code, say something like this
1328 static void
1330 cb1()
1331 {
1332 printf ("Fatal Error\n");
1333 exit(1);
1334 }
1335 Now change that to call a Perl subroutine instead
1337 static SV * callback = (SV*)NULL;
1339 static void
1341 cb1()
1342 {
1343 dSP;
1344 PUSHMARK(SP);
1346 /* Call the Perl sub to process the callback */
1348 call_sv(callback, G_DISCARD);
1349 }
1350 void
1353 register_fatal(fn)
1354 SV * fn
1355 CODE:
1356 /* Remember the Perl sub */
1357 if (callback == (SV*)NULL)
1358 callback = newSVsv(fn);
1359 else
1360 SvSetSV(callback, fn);
1361 /* register the callback with the external library */
1363 register_fatal(cb1);
1364 where the Perl equivalent of "register_fatal" and the callback it
1366 registers, "pcb1", might look like this
1367 # Register the sub pcb1
1369 register_fatal(\&pcb1);
1370 sub pcb1
1372 {
1373 die "I'm dying...\n";
1374 }
1375 The mapping between the C callback and the Perl equivalent is stored in
1377 the global variable "callback".
1378 This will be adequate if you ever need to have only one callback
1380 registered at any time. An example could be an error handler like the
1381 code sketched out above. Remember though, repeated calls to
1382 "register_fatal" will replace the previously registered callback
1383 function with the new one.
1384 Say for example you want to interface to a library which allows
1386 asynchronous file i/o. In this case you may be able to register a
1387 callback whenever a read operation has completed. To be of any use we
1388 want to be able to call separate Perl subroutines for each file that is
1389 opened. As it stands, the error handler example above would not be
1390 adequate as it allows only a single callback to be defined at any time.
1391 What we require is a means of storing the mapping between the opened
1392 file and the Perl subroutine we want to be called for that file.
1393 Say the i/o library has a function "asynch_read" which associates a C
1395 function "ProcessRead" with a file handle "fh"--this assumes that it
1396 has also provided some routine to open the file and so obtain the file
1397 handle.
1398 asynch_read(fh, ProcessRead)
1400 This may expect the C ProcessRead function of this form
1402 void
1404 ProcessRead(fh, buffer)
1405 int fh;
1406 char * buffer;
1407 {
1408 ...
1409 }
1410 To provide a Perl interface to this library we need to be able to map
1412 between the "fh" parameter and the Perl subroutine we want called. A
1413 hash is a convenient mechanism for storing this mapping. The code
1414 below shows a possible implementation
1415 static HV * Mapping = (HV*)NULL;
1417 void
1419 asynch_read(fh, callback)
1420 int fh
1421 SV * callback
1422 CODE:
1423 /* If the hash doesn't already exist, create it */
1424 if (Mapping == (HV*)NULL)
1425 Mapping = newHV();
1426 /* Save the fh -> callback mapping */
1428 hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
1429 /* Register with the C Library */
1431 asynch_read(fh, asynch_read_if);
1432 and "asynch_read_if" could look like this
1434 static void
1436 asynch_read_if(fh, buffer)
1437 int fh;
1438 char * buffer;
1439 {
1440 dSP;
1441 SV ** sv;
1442 /* Get the callback associated with fh */
1444 sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
1445 if (sv == (SV**)NULL)
1446 croak("Internal error...\n");
1447 PUSHMARK(SP);
1449 EXTEND(SP, 2);
1450 PUSHs(sv_2mortal(newSViv(fh)));
1451 PUSHs(sv_2mortal(newSVpv(buffer, 0)));
1452 PUTBACK;
1453 /* Call the Perl sub */
1455 call_sv(*sv, G_DISCARD);
1456 }
1457 For completeness, here is "asynch_close". This shows how to remove the
1459 entry from the hash "Mapping".
1460 void
1462 asynch_close(fh)
1463 int fh
1464 CODE:
1465 /* Remove the entry from the hash */
1466 (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
1467 /* Now call the real asynch_close */
1469 asynch_close(fh);
1470 So the Perl interface would look like this
1472 sub callback1
1474 {
1475 my($handle, $buffer) = @_;
1476 }
1477 # Register the Perl callback
1479 asynch_read($fh, \&callback1);
1480 asynch_close($fh);
1482 The mapping between the C callback and Perl is stored in the global
1484 hash "Mapping" this time. Using a hash has the distinct advantage that
1485 it allows an unlimited number of callbacks to be registered.
1486 What if the interface provided by the C callback doesn't contain a
1488 parameter which allows the file handle to Perl subroutine mapping? Say
1489 in the asynchronous i/o package, the callback function gets passed only
1490 the "buffer" parameter like this
1491 void
1493 ProcessRead(buffer)
1494 char * buffer;
1495 {
1496 ...
1497 }
1498 Without the file handle there is no straightforward way to map from the
1500 C callback to the Perl subroutine.
1501 In this case a possible way around this problem is to predefine a
1503 series of C functions to act as the interface to Perl, thus
1504 #define MAX_CB 3
1506 #define NULL_HANDLE -1
1507 typedef void (*FnMap)();
1508 struct MapStruct {
1510 FnMap Function;
1511 SV * PerlSub;
1512 int Handle;
1513 };
1514 static void fn1();
1516 static void fn2();
1517 static void fn3();
1518 static struct MapStruct Map [MAX_CB] =
1520 {
1521 { fn1, NULL, NULL_HANDLE },
1522 { fn2, NULL, NULL_HANDLE },
1523 { fn3, NULL, NULL_HANDLE }
1524 };
1525 static void
1527 Pcb(index, buffer)
1528 int index;
1529 char * buffer;
1530 {
1531 dSP;
1532 PUSHMARK(SP);
1534 XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
1535 PUTBACK;
1536 /* Call the Perl sub */
1538 call_sv(Map[index].PerlSub, G_DISCARD);
1539 }
1540 static void
1542 fn1(buffer)
1543 char * buffer;
1544 {
1545 Pcb(0, buffer);
1546 }
1547 static void
1549 fn2(buffer)
1550 char * buffer;
1551 {
1552 Pcb(1, buffer);
1553 }
1554 static void
1556 fn3(buffer)
1557 char * buffer;
1558 {
1559 Pcb(2, buffer);
1560 }
1561 void
1563 array_asynch_read(fh, callback)
1564 int fh
1565 SV * callback
1566 CODE:
1567 int index;
1568 int null_index = MAX_CB;
1569 /* Find the same handle or an empty entry */
1571 for (index = 0; index < MAX_CB; ++index)
1572 {
1573 if (Map[index].Handle == fh)
1574 break;
1575 if (Map[index].Handle == NULL_HANDLE)
1577 null_index = index;
1578 }
1579 if (index == MAX_CB && null_index == MAX_CB)
1581 croak ("Too many callback functions registered\n");
1582 if (index == MAX_CB)
1584 index = null_index;
1585 /* Save the file handle */
1587 Map[index].Handle = fh;
1588 /* Remember the Perl sub */
1590 if (Map[index].PerlSub == (SV*)NULL)
1591 Map[index].PerlSub = newSVsv(callback);
1592 else
1593 SvSetSV(Map[index].PerlSub, callback);
1594 asynch_read(fh, Map[index].Function);
1596 void
1598 array_asynch_close(fh)
1599 int fh
1600 CODE:
1601 int index;
1602 /* Find the file handle */
1604 for (index = 0; index < MAX_CB; ++ index)
1605 if (Map[index].Handle == fh)
1606 break;
1607 if (index == MAX_CB)
1609 croak ("could not close fh %d\n", fh);
1610 Map[index].Handle = NULL_HANDLE;
1612 SvREFCNT_dec(Map[index].PerlSub);
1613 Map[index].PerlSub = (SV*)NULL;
1614 asynch_close(fh);
1616 In this case the functions "fn1", "fn2", and "fn3" are used to remember
1618 the Perl subroutine to be called. Each of the functions holds a
1619 separate hard-wired index which is used in the function "Pcb" to access
1620 the "Map" array and actually call the Perl subroutine.
1621 There are some obvious disadvantages with this technique.
1623 Firstly, the code is considerably more complex than with the previous
1625 example.
1626 Secondly, there is a hard-wired limit (in this case 3) to the number of
1628 callbacks that can exist simultaneously. The only way to increase the
1629 limit is by modifying the code to add more functions and then
1630 recompiling. None the less, as long as the number of functions is
1631 chosen with some care, it is still a workable solution and in some
1632 cases is the only one available.
1633 To summarize, here are a number of possible methods for you to consider
1635 for storing the mapping between C and the Perl callback
1636 1. Ignore the problem - Allow only 1 callback
1638 For a lot of situations, like interfacing to an error handler,
1639 this may be a perfectly adequate solution.
1640 2. Create a sequence of callbacks - hard wired limit
1642 If it is impossible to tell from the parameters passed back from
1643 the C callback what the context is, then you may need to create a
1644 sequence of C callback interface functions, and store pointers to
1645 each in an array.
1646 3. Use a parameter to map to the Perl callback
1648 A hash is an ideal mechanism to store the mapping between C and
1649 Perl.
1650 Alternate Stack Manipulation
1652 Although I have made use of only the "POP*" macros to access values
1653 returned from Perl subroutines, it is also possible to bypass these
1654 macros and read the stack using the "ST" macro (See perlxs for a full
1655 description of the "ST" macro).
1656 Most of the time the "POP*" macros should be adequate; the main problem
1658 with them is that they force you to process the returned values in
1659 sequence. This may not be the most suitable way to process the values
1660 in some cases. What we want is to be able to access the stack in a
1661 random order. The "ST" macro as used when coding an XSUB is ideal for
1662 this purpose.
1663 The code below is the example given in the section "Returning a List of
1665 Values" recoded to use "ST" instead of "POP*".
1666 static void
1668 call_AddSubtract2(a, b)
1669 int a;
1670 int b;
1671 {
1672 dSP;
1673 I32 ax;
1674 int count;
1675 ENTER;
1677 SAVETMPS;
1678 PUSHMARK(SP);
1680 EXTEND(SP, 2);
1681 PUSHs(sv_2mortal(newSViv(a)));
1682 PUSHs(sv_2mortal(newSViv(b)));
1683 PUTBACK;
1684 count = call_pv("AddSubtract", G_ARRAY);
1686 SPAGAIN;
1688 SP -= count;
1689 ax = (SP - PL_stack_base) + 1;
1690 if (count != 2)
1692 croak("Big trouble\n");
1693 printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
1695 printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));
1696 PUTBACK;
1698 FREETMPS;
1699 LEAVE;
1700 }
1701 Notes
1703 1. Notice that it was necessary to define the variable "ax". This is
1705 because the "ST" macro expects it to exist. If we were in an XSUB
1706 it would not be necessary to define "ax" as it is already defined
1707 for us.
1708 2. The code
1710 SPAGAIN;
1712 SP -= count;
1713 ax = (SP - PL_stack_base) + 1;
1714 sets the stack up so that we can use the "ST" macro.
1716 3. Unlike the original coding of this example, the returned values
1718 are not accessed in reverse order. So ST(0) refers to the first
1719 value returned by the Perl subroutine and "ST(count-1)" refers to
1720 the last.
1721 Creating and Calling an Anonymous Subroutine in C
1723 As we've already shown, "call_sv" can be used to invoke an anonymous
1724 subroutine. However, our example showed a Perl script invoking an XSUB
1725 to perform this operation. Let's see how it can be done inside our C
1726 code:
1727 ...
1729 SV *cvrv
1731 = eval_pv("sub {
1732 print 'You will not find me cluttering any namespace!'
1733 }", TRUE);
1734 ...
1736 call_sv(cvrv, G_VOID|G_NOARGS);
1738 "eval_pv" is used to compile the anonymous subroutine, which will be
1740 the return value as well (read more about "eval_pv" in "eval_pv" in
1741 perlapi). Once this code reference is in hand, it can be mixed in with
1742 all the previous examples we've shown.
1743
1745 Sometimes you need to invoke the same subroutine repeatedly. This
1746 usually happens with a function that acts on a list of values, such as
1747 Perl's built-in sort(). You can pass a comparison function to sort(),
1748 which will then be invoked for every pair of values that needs to be
1749 compared. The first() and reduce() functions from List::Util follow a
1750 similar pattern.
1751 In this case it is possible to speed up the routine (often quite
1753 substantially) by using the lightweight callback API. The idea is that
1754 the calling context only needs to be created and destroyed once, and
1755 the sub can be called arbitrarily many times in between.
1756 It is usual to pass parameters using global variables (typically $_ for
1758 one parameter, or $a and $b for two parameters) rather than via @_. (It
1759 is possible to use the @_ mechanism if you know what you're doing,
1760 though there is as yet no supported API for it. It's also inherently
1761 slower.)
1762 The pattern of macro calls is like this:
1764 dMULTICALL; /* Declare local variables */
1766 U8 gimme = G_SCALAR; /* context of the call: G_SCALAR,
1767 * G_ARRAY, or G_VOID */
1768 PUSH_MULTICALL(cv); /* Set up the context for calling cv,
1770 and set local vars appropriately */
1771 /* loop */ {
1773 /* set the value(s) af your parameter variables */
1774 MULTICALL; /* Make the actual call */
1775 } /* end of loop */
1776 POP_MULTICALL; /* Tear down the calling context */
1778 For some concrete examples, see the implementation of the first() and
1780 reduce() functions of List::Util 1.18. There you will also find a
1781 header file that emulates the multicall API on older versions of perl.
1782
1784 perlxs, perlguts, perlembed
1785
1787 Paul Marquess
1788 Special thanks to the following people who assisted in the creation of
1790 the document.
1791 Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
1793 and Larry Wall.
1794
1796 Last updated for perl 5.23.1.
1797perl v5.32.1 2021-05-31 PERLCALL(1)