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