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