Exporter-5.72 is now on the CPAN
[perl.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, I<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 I<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 I<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 I<Returning a list in a 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 I<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 I<Returning a Scalar> gives details of how to
236 dispose of these temporaries explicitly and the section I<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 I<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 I<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 I<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 I<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         XPUSHs(sv_2mortal(newSVpv(a, 0)));
470         XPUSHs(sv_2mortal(newSViv(b)));
471         PUTBACK;
472
473         call_pv("LeftString", G_DISCARD);
474
475         FREETMPS;
476         LEAVE;
477     }
478
479 Here are a few notes on the C function I<call_LeftString>.
480
481 =over 5
482
483 =item 1.
484
485 Parameters are passed to the Perl subroutine using the Perl stack.
486 This is the purpose of the code beginning with the line C<dSP> and
487 ending with the line C<PUTBACK>.  The C<dSP> declares a local copy
488 of the stack pointer.  This local copy should B<always> be accessed
489 as C<SP>.
490
491 =item 2.
492
493 If you are going to put something onto the Perl stack, you need to know
494 where to put it. This is the purpose of the macro C<dSP>--it declares
495 and initializes a I<local> copy of the Perl stack pointer.
496
497 All the other macros which will be used in this example require you to
498 have used this macro.
499
500 The exception to this rule is if you are calling a Perl subroutine
501 directly from an XSUB function. In this case it is not necessary to
502 use the C<dSP> macro explicitly--it will be declared for you
503 automatically.
504
505 =item 3.
506
507 Any parameters to be pushed onto the stack should be bracketed by the
508 C<PUSHMARK> and C<PUTBACK> macros.  The purpose of these two macros, in
509 this context, is to count the number of parameters you are
510 pushing automatically.  Then whenever Perl is creating the C<@_> array for the
511 subroutine, it knows how big to make it.
512
513 The C<PUSHMARK> macro tells Perl to make a mental note of the current
514 stack pointer. Even if you aren't passing any parameters (like the
515 example shown in the section I<No Parameters, Nothing Returned>) you
516 must still call the C<PUSHMARK> macro before you can call any of the
517 I<call_*> functions--Perl still needs to know that there are no
518 parameters.
519
520 The C<PUTBACK> macro sets the global copy of the stack pointer to be
521 the same as our local copy. If we didn't do this, I<call_pv>
522 wouldn't know where the two parameters we pushed were--remember that
523 up to now all the stack pointer manipulation we have done is with our
524 local copy, I<not> the global copy.
525
526 =item 4.
527
528 Next, we come to XPUSHs. This is where the parameters actually get
529 pushed onto the stack. In this case we are pushing a string and an
530 integer.
531
532 See L<perlguts/"XSUBs and the Argument Stack"> for details
533 on how the XPUSH macros work.
534
535 =item 5.
536
537 Because we created temporary values (by means of sv_2mortal() calls)
538 we will have to tidy up the Perl stack and dispose of mortal SVs.
539
540 This is the purpose of
541
542     ENTER;
543     SAVETMPS;
544
545 at the start of the function, and
546
547     FREETMPS;
548     LEAVE;
549
550 at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
551 temporaries we create.  This means that the temporaries we get rid of
552 will be limited to those which were created after these calls.
553
554 The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
555 the Perl subroutine (see next example), plus it will also dump the
556 mortal SVs we have created.  Having C<ENTER>/C<SAVETMPS> at the
557 beginning of the code makes sure that no other mortals are destroyed.
558
559 Think of these macros as working a bit like C<{> and C<}> in Perl
560 to limit the scope of local variables.
561
562 See the section I<Using Perl to Dispose of Temporaries> for details of
563 an alternative to using these macros.
564
565 =item 6.
566
567 Finally, I<LeftString> can now be called via the I<call_pv> function.
568 The only flag specified this time is G_DISCARD. Because we are passing
569 2 parameters to the Perl subroutine this time, we have not specified
570 G_NOARGS.
571
572 =back
573
574 =head2 Returning a Scalar
575
576 Now for an example of dealing with the items returned from a Perl
577 subroutine.
578
579 Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
580 and simply returns their sum.
581
582     sub Adder
583     {
584         my($a, $b) = @_;
585         $a + $b;
586     }
587
588 Because we are now concerned with the return value from I<Adder>, the C
589 function required to call it is now a bit more complex.
590
591     static void
592     call_Adder(a, b)
593     int a;
594     int b;
595     {
596         dSP;
597         int count;
598
599         ENTER;
600         SAVETMPS;
601
602         PUSHMARK(SP);
603         XPUSHs(sv_2mortal(newSViv(a)));
604         XPUSHs(sv_2mortal(newSViv(b)));
605         PUTBACK;
606
607         count = call_pv("Adder", G_SCALAR);
608
609         SPAGAIN;
610
611         if (count != 1)
612             croak("Big trouble\n");
613
614         printf ("The sum of %d and %d is %d\n", a, b, POPi);
615
616         PUTBACK;
617         FREETMPS;
618         LEAVE;
619     }
620
621 Points to note this time are
622
623 =over 5
624
625 =item 1.
626
627 The only flag specified this time was G_SCALAR. That means that the C<@_>
628 array will be created and that the value returned by I<Adder> will
629 still exist after the call to I<call_pv>.
630
631 =item 2.
632
633 The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
634 stack pointer. This is necessary because it is possible that the memory
635 allocated to the Perl stack has been reallocated during the
636 I<call_pv> call.
637
638 If you are making use of the Perl stack pointer in your code you must
639 always refresh the local copy using SPAGAIN whenever you make use
640 of the I<call_*> functions or any other Perl internal function.
641
642 =item 3.
643
644 Although only a single value was expected to be returned from I<Adder>,
645 it is still good practice to check the return code from I<call_pv>
646 anyway.
647
648 Expecting a single value is not quite the same as knowing that there
649 will be one. If someone modified I<Adder> to return a list and we
650 didn't check for that possibility and take appropriate action the Perl
651 stack would end up in an inconsistent state. That is something you
652 I<really> don't want to happen ever.
653
654 =item 4.
655
656 The C<POPi> macro is used here to pop the return value from the stack.
657 In this case we wanted an integer, so C<POPi> was used.
658
659
660 Here is the complete list of POP macros available, along with the types
661 they return.
662
663     POPs        SV
664     POPp        pointer
665     POPn        double
666     POPi        integer
667     POPl        long
668
669 =item 5.
670
671 The final C<PUTBACK> is used to leave the Perl stack in a consistent
672 state before exiting the function.  This is necessary because when we
673 popped the return value from the stack with C<POPi> it updated only our
674 local copy of the stack pointer.  Remember, C<PUTBACK> sets the global
675 stack pointer to be the same as our local copy.
676
677 =back
678
679
680 =head2 Returning a List of Values
681
682 Now, let's extend the previous example to return both the sum of the
683 parameters and the difference.
684
685 Here is the Perl subroutine
686
687     sub AddSubtract
688     {
689        my($a, $b) = @_;
690        ($a+$b, $a-$b);
691     }
692
693 and this is the C function
694
695     static void
696     call_AddSubtract(a, b)
697     int a;
698     int b;
699     {
700         dSP;
701         int count;
702
703         ENTER;
704         SAVETMPS;
705
706         PUSHMARK(SP);
707         XPUSHs(sv_2mortal(newSViv(a)));
708         XPUSHs(sv_2mortal(newSViv(b)));
709         PUTBACK;
710
711         count = call_pv("AddSubtract", G_ARRAY);
712
713         SPAGAIN;
714
715         if (count != 2)
716             croak("Big trouble\n");
717
718         printf ("%d - %d = %d\n", a, b, POPi);
719         printf ("%d + %d = %d\n", a, b, POPi);
720
721         PUTBACK;
722         FREETMPS;
723         LEAVE;
724     }
725
726 If I<call_AddSubtract> is called like this
727
728     call_AddSubtract(7, 4);
729
730 then here is the output
731
732     7 - 4 = 3
733     7 + 4 = 11
734
735 Notes
736
737 =over 5
738
739 =item 1.
740
741 We wanted list context, so G_ARRAY was used.
742
743 =item 2.
744
745 Not surprisingly C<POPi> is used twice this time because we were
746 retrieving 2 values from the stack. The important thing to note is that
747 when using the C<POP*> macros they come off the stack in I<reverse>
748 order.
749
750 =back
751
752 =head2 Returning a List in a Scalar Context
753
754 Say the Perl subroutine in the previous section was called in a scalar
755 context, like this
756
757     static void
758     call_AddSubScalar(a, b)
759     int a;
760     int b;
761     {
762         dSP;
763         int count;
764         int i;
765
766         ENTER;
767         SAVETMPS;
768
769         PUSHMARK(SP);
770         XPUSHs(sv_2mortal(newSViv(a)));
771         XPUSHs(sv_2mortal(newSViv(b)));
772         PUTBACK;
773
774         count = call_pv("AddSubtract", G_SCALAR);
775
776         SPAGAIN;
777
778         printf ("Items Returned = %d\n", count);
779
780         for (i = 1; i <= count; ++i)
781             printf ("Value %d = %d\n", i, POPi);
782
783         PUTBACK;
784         FREETMPS;
785         LEAVE;
786     }
787
788 The other modification made is that I<call_AddSubScalar> will print the
789 number of items returned from the Perl subroutine and their value (for
790 simplicity it assumes that they are integer).  So if
791 I<call_AddSubScalar> is called
792
793     call_AddSubScalar(7, 4);
794
795 then the output will be
796
797     Items Returned = 1
798     Value 1 = 3
799
800 In this case the main point to note is that only the last item in the
801 list is returned from the subroutine. I<AddSubtract> actually made it back to
802 I<call_AddSubScalar>.
803
804
805 =head2 Returning Data from Perl via the Parameter List
806
807 It is also possible to return values directly via the parameter
808 list--whether it is actually desirable to do it is another matter entirely.
809
810 The Perl subroutine, I<Inc>, below takes 2 parameters and increments
811 each directly.
812
813     sub Inc
814     {
815         ++ $_[0];
816         ++ $_[1];
817     }
818
819 and here is a C function to call it.
820
821     static void
822     call_Inc(a, b)
823     int a;
824     int b;
825     {
826         dSP;
827         int count;
828         SV * sva;
829         SV * svb;
830
831         ENTER;
832         SAVETMPS;
833
834         sva = sv_2mortal(newSViv(a));
835         svb = sv_2mortal(newSViv(b));
836
837         PUSHMARK(SP);
838         XPUSHs(sva);
839         XPUSHs(svb);
840         PUTBACK;
841
842         count = call_pv("Inc", G_DISCARD);
843
844         if (count != 0)
845             croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
846                    count);
847
848         printf ("%d + 1 = %d\n", a, SvIV(sva));
849         printf ("%d + 1 = %d\n", b, SvIV(svb));
850
851         FREETMPS;
852         LEAVE;
853     }
854
855 To be able to access the two parameters that were pushed onto the stack
856 after they return from I<call_pv> it is necessary to make a note
857 of their addresses--thus the two variables C<sva> and C<svb>.
858
859 The reason this is necessary is that the area of the Perl stack which
860 held them will very likely have been overwritten by something else by
861 the time control returns from I<call_pv>.
862
863
864
865
866 =head2 Using G_EVAL
867
868 Now an example using G_EVAL. Below is a Perl subroutine which computes
869 the difference of its 2 parameters. If this would result in a negative
870 result, the subroutine calls I<die>.
871
872     sub Subtract
873     {
874         my ($a, $b) = @_;
875
876         die "death can be fatal\n" if $a < $b;
877
878         $a - $b;
879     }
880
881 and some C to call it
882
883     static void
884     call_Subtract(a, b)
885     int a;
886     int b;
887     {
888         dSP;
889         int count;
890
891         ENTER;
892         SAVETMPS;
893
894         PUSHMARK(SP);
895         XPUSHs(sv_2mortal(newSViv(a)));
896         XPUSHs(sv_2mortal(newSViv(b)));
897         PUTBACK;
898
899         count = call_pv("Subtract", G_EVAL|G_SCALAR);
900
901         SPAGAIN;
902
903         /* Check the eval first */
904         if (SvTRUE(ERRSV))
905         {
906             printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
907             POPs;
908         }
909         else
910         {
911             if (count != 1)
912                croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
913                         count);
914
915             printf ("%d - %d = %d\n", a, b, POPi);
916         }
917
918         PUTBACK;
919         FREETMPS;
920         LEAVE;
921     }
922
923 If I<call_Subtract> is called thus
924
925     call_Subtract(4, 5)
926
927 the following will be printed
928
929     Uh oh - death can be fatal
930
931 Notes
932
933 =over 5
934
935 =item 1.
936
937 We want to be able to catch the I<die> so we have used the G_EVAL
938 flag.  Not specifying this flag would mean that the program would
939 terminate immediately at the I<die> statement in the subroutine
940 I<Subtract>.
941
942 =item 2.
943
944 The code
945
946     if (SvTRUE(ERRSV))
947     {
948         printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
949         POPs;
950     }
951
952 is the direct equivalent of this bit of Perl
953
954     print "Uh oh - $@\n" if $@;
955
956 C<PL_errgv> is a perl global of type C<GV *> that points to the
957 symbol table entry containing the error.  C<ERRSV> therefore
958 refers to the C equivalent of C<$@>.
959
960 =item 3.
961
962 Note that the stack is popped using C<POPs> in the block where
963 C<SvTRUE(ERRSV)> is true.  This is necessary because whenever a
964 I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
965 the top of the stack holds the value I<undef>. Because we want the
966 program to continue after detecting this error, it is essential that
967 the stack be tidied up by removing the I<undef>.
968
969 =back
970
971
972 =head2 Using G_KEEPERR
973
974 Consider this rather facetious example, where we have used an XS
975 version of the call_Subtract example above inside a destructor:
976
977     package Foo;
978     sub new { bless {}, $_[0] }
979     sub Subtract {
980         my($a,$b) = @_;
981         die "death can be fatal" if $a < $b;
982         $a - $b;
983     }
984     sub DESTROY { call_Subtract(5, 4); }
985     sub foo { die "foo dies"; }
986
987     package main;
988     {
989         my $foo = Foo->new;
990         eval { $foo->foo };
991     }
992     print "Saw: $@" if $@;             # should be, but isn't
993
994 This example will fail to recognize that an error occurred inside the
995 C<eval {}>.  Here's why: the call_Subtract code got executed while perl
996 was cleaning up temporaries when exiting the outer braced block, and because
997 call_Subtract is implemented with I<call_pv> using the G_EVAL
998 flag, it promptly reset C<$@>.  This results in the failure of the
999 outermost test for C<$@>, and thereby the failure of the error trap.
1000
1001 Appending the G_KEEPERR flag, so that the I<call_pv> call in
1002 call_Subtract reads:
1003
1004         count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
1005
1006 will preserve the error and restore reliable error handling.
1007
1008 =head2 Using call_sv
1009
1010 In all the previous examples I have 'hard-wired' the name of the Perl
1011 subroutine to be called from C.  Most of the time though, it is more
1012 convenient to be able to specify the name of the Perl subroutine from
1013 within the Perl script.
1014
1015 Consider the Perl code below
1016
1017     sub fred
1018     {
1019         print "Hello there\n";
1020     }
1021
1022     CallSubPV("fred");
1023
1024 Here is a snippet of XSUB which defines I<CallSubPV>.
1025
1026     void
1027     CallSubPV(name)
1028         char *  name
1029         CODE:
1030         PUSHMARK(SP);
1031         call_pv(name, G_DISCARD|G_NOARGS);
1032
1033 That is fine as far as it goes. The thing is, the Perl subroutine
1034 can be specified as only a string, however, Perl allows references
1035 to subroutines and anonymous subroutines.
1036 This is where I<call_sv> is useful.
1037
1038 The code below for I<CallSubSV> is identical to I<CallSubPV> except
1039 that the C<name> parameter is now defined as an SV* and we use
1040 I<call_sv> instead of I<call_pv>.
1041
1042     void
1043     CallSubSV(name)
1044         SV *    name
1045         CODE:
1046         PUSHMARK(SP);
1047         call_sv(name, G_DISCARD|G_NOARGS);
1048
1049 Because we are using an SV to call I<fred> the following can all be used:
1050
1051     CallSubSV("fred");
1052     CallSubSV(\&fred);
1053     $ref = \&fred;
1054     CallSubSV($ref);
1055     CallSubSV( sub { print "Hello there\n" } );
1056
1057 As you can see, I<call_sv> gives you much greater flexibility in
1058 how you can specify the Perl subroutine.
1059
1060 You should note that, if it is necessary to store the SV (C<name> in the
1061 example above) which corresponds to the Perl subroutine so that it can
1062 be used later in the program, it not enough just to store a copy of the
1063 pointer to the SV. Say the code above had been like this:
1064
1065     static SV * rememberSub;
1066
1067     void
1068     SaveSub1(name)
1069         SV *    name
1070         CODE:
1071         rememberSub = name;
1072
1073     void
1074     CallSavedSub1()
1075         CODE:
1076         PUSHMARK(SP);
1077         call_sv(rememberSub, G_DISCARD|G_NOARGS);
1078
1079 The reason this is wrong is that, by the time you come to use the
1080 pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1081 to the Perl subroutine that was recorded in C<SaveSub1>.  This is
1082 particularly true for these cases:
1083
1084     SaveSub1(\&fred);
1085     CallSavedSub1();
1086
1087     SaveSub1( sub { print "Hello there\n" } );
1088     CallSavedSub1();
1089
1090 By the time each of the C<SaveSub1> statements above has been executed,
1091 the SV*s which corresponded to the parameters will no longer exist.
1092 Expect an error message from Perl of the form
1093
1094     Can't use an undefined value as a subroutine reference at ...
1095
1096 for each of the C<CallSavedSub1> lines.
1097
1098 Similarly, with this code
1099
1100     $ref = \&fred;
1101     SaveSub1($ref);
1102     $ref = 47;
1103     CallSavedSub1();
1104
1105 you can expect one of these messages (which you actually get is dependent on
1106 the version of Perl you are using)
1107
1108     Not a CODE reference at ...
1109     Undefined subroutine &main::47 called ...
1110
1111 The variable $ref may have referred to the subroutine C<fred>
1112 whenever the call to C<SaveSub1> was made but by the time
1113 C<CallSavedSub1> gets called it now holds the number C<47>. Because we
1114 saved only a pointer to the original SV in C<SaveSub1>, any changes to
1115 $ref will be tracked by the pointer C<rememberSub>. This means that
1116 whenever C<CallSavedSub1> gets called, it will attempt to execute the
1117 code which is referenced by the SV* C<rememberSub>.  In this case
1118 though, it now refers to the integer C<47>, so expect Perl to complain
1119 loudly.
1120
1121 A similar but more subtle problem is illustrated with this code:
1122
1123     $ref = \&fred;
1124     SaveSub1($ref);
1125     $ref = \&joe;
1126     CallSavedSub1();
1127
1128 This time whenever C<CallSavedSub1> gets called it will execute the Perl
1129 subroutine C<joe> (assuming it exists) rather than C<fred> as was
1130 originally requested in the call to C<SaveSub1>.
1131
1132 To get around these problems it is necessary to take a full copy of the
1133 SV.  The code below shows C<SaveSub2> modified to do that.
1134
1135     static SV * keepSub = (SV*)NULL;
1136
1137     void
1138     SaveSub2(name)
1139         SV *    name
1140         CODE:
1141         /* Take a copy of the callback */
1142         if (keepSub == (SV*)NULL)
1143             /* First time, so create a new SV */
1144             keepSub = newSVsv(name);
1145         else
1146             /* Been here before, so overwrite */
1147             SvSetSV(keepSub, name);
1148
1149     void
1150     CallSavedSub2()
1151         CODE:
1152         PUSHMARK(SP);
1153         call_sv(keepSub, G_DISCARD|G_NOARGS);
1154
1155 To avoid creating a new SV every time C<SaveSub2> is called,
1156 the function first checks to see if it has been called before.  If not,
1157 then space for a new SV is allocated and the reference to the Perl
1158 subroutine C<name> is copied to the variable C<keepSub> in one
1159 operation using C<newSVsv>.  Thereafter, whenever C<SaveSub2> is called,
1160 the existing SV, C<keepSub>, is overwritten with the new value using
1161 C<SvSetSV>.
1162
1163 =head2 Using call_argv
1164
1165 Here is a Perl subroutine which prints whatever parameters are passed
1166 to it.
1167
1168     sub PrintList
1169     {
1170         my(@list) = @_;
1171
1172         foreach (@list) { print "$_\n" }
1173     }
1174
1175 And here is an example of I<call_argv> which will call
1176 I<PrintList>.
1177
1178     static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
1179
1180     static void
1181     call_PrintList()
1182     {
1183         dSP;
1184
1185         call_argv("PrintList", G_DISCARD, words);
1186     }
1187
1188 Note that it is not necessary to call C<PUSHMARK> in this instance.
1189 This is because I<call_argv> will do it for you.
1190
1191 =head2 Using call_method
1192
1193 Consider the following Perl code:
1194
1195     {
1196         package Mine;
1197
1198         sub new
1199         {
1200             my($type) = shift;
1201             bless [@_]
1202         }
1203
1204         sub Display
1205         {
1206             my ($self, $index) = @_;
1207             print "$index: $$self[$index]\n";
1208         }
1209
1210         sub PrintID
1211         {
1212             my($class) = @_;
1213             print "This is Class $class version 1.0\n";
1214         }
1215     }
1216
1217 It implements just a very simple class to manage an array.  Apart from
1218 the constructor, C<new>, it declares methods, one static and one
1219 virtual. The static method, C<PrintID>, prints out simply the class
1220 name and a version number. The virtual method, C<Display>, prints out a
1221 single element of the array.  Here is an all-Perl example of using it.
1222
1223     $a = Mine->new('red', 'green', 'blue');
1224     $a->Display(1);
1225     Mine->PrintID;
1226
1227 will print
1228
1229     1: green
1230     This is Class Mine version 1.0
1231
1232 Calling a Perl method from C is fairly straightforward. The following
1233 things are required:
1234
1235 =over 5
1236
1237 =item *
1238
1239 A reference to the object for a virtual method or the name of the class
1240 for a static method
1241
1242 =item *
1243
1244 The name of the method
1245
1246 =item *
1247
1248 Any other parameters specific to the method
1249
1250 =back
1251
1252 Here is a simple XSUB which illustrates the mechanics of calling both
1253 the C<PrintID> and C<Display> methods from C.
1254
1255     void
1256     call_Method(ref, method, index)
1257         SV *    ref
1258         char *  method
1259         int             index
1260         CODE:
1261         PUSHMARK(SP);
1262         XPUSHs(ref);
1263         XPUSHs(sv_2mortal(newSViv(index)));
1264         PUTBACK;
1265
1266         call_method(method, G_DISCARD);
1267
1268     void
1269     call_PrintID(class, method)
1270         char *  class
1271         char *  method
1272         CODE:
1273         PUSHMARK(SP);
1274         XPUSHs(sv_2mortal(newSVpv(class, 0)));
1275         PUTBACK;
1276
1277         call_method(method, G_DISCARD);
1278
1279
1280 So the methods C<PrintID> and C<Display> can be invoked like this:
1281
1282     $a = Mine->new('red', 'green', 'blue');
1283     call_Method($a, 'Display', 1);
1284     call_PrintID('Mine', 'PrintID');
1285
1286 The only thing to note is that, in both the static and virtual methods,
1287 the method name is not passed via the stack--it is used as the first
1288 parameter to I<call_method>.
1289
1290 =head2 Using GIMME_V
1291
1292 Here is a trivial XSUB which prints the context in which it is
1293 currently executing.
1294
1295     void
1296     PrintContext()
1297         CODE:
1298         I32 gimme = GIMME_V;
1299         if (gimme == G_VOID)
1300             printf ("Context is Void\n");
1301         else if (gimme == G_SCALAR)
1302             printf ("Context is Scalar\n");
1303         else
1304             printf ("Context is Array\n");
1305
1306 And here is some Perl to test it.
1307
1308     PrintContext;
1309     $a = PrintContext;
1310     @a = PrintContext;
1311
1312 The output from that will be
1313
1314     Context is Void
1315     Context is Scalar
1316     Context is Array
1317
1318 =head2 Using Perl to Dispose of Temporaries
1319
1320 In the examples given to date, any temporaries created in the callback
1321 (i.e., parameters passed on the stack to the I<call_*> function or
1322 values returned via the stack) have been freed by one of these methods:
1323
1324 =over 5
1325
1326 =item *
1327
1328 Specifying the G_DISCARD flag with I<call_*>
1329
1330 =item *
1331
1332 Explicitly using the C<ENTER>/C<SAVETMPS>--C<FREETMPS>/C<LEAVE> pairing
1333
1334 =back
1335
1336 There is another method which can be used, namely letting Perl do it
1337 for you automatically whenever it regains control after the callback
1338 has terminated.  This is done by simply not using the
1339
1340     ENTER;
1341     SAVETMPS;
1342     ...
1343     FREETMPS;
1344     LEAVE;
1345
1346 sequence in the callback (and not, of course, specifying the G_DISCARD
1347 flag).
1348
1349 If you are going to use this method you have to be aware of a possible
1350 memory leak which can arise under very specific circumstances.  To
1351 explain these circumstances you need to know a bit about the flow of
1352 control between Perl and the callback routine.
1353
1354 The examples given at the start of the document (an error handler and
1355 an event driven program) are typical of the two main sorts of flow
1356 control that you are likely to encounter with callbacks.  There is a
1357 very important distinction between them, so pay attention.
1358
1359 In the first example, an error handler, the flow of control could be as
1360 follows.  You have created an interface to an external library.
1361 Control can reach the external library like this
1362
1363     perl --> XSUB --> external library
1364
1365 Whilst control is in the library, an error condition occurs. You have
1366 previously set up a Perl callback to handle this situation, so it will
1367 get executed. Once the callback has finished, control will drop back to
1368 Perl again.  Here is what the flow of control will be like in that
1369 situation
1370
1371     perl --> XSUB --> external library
1372                       ...
1373                       error occurs
1374                       ...
1375                       external library --> call_* --> perl
1376                                                           |
1377     perl <-- XSUB <-- external library <-- call_* <----+
1378
1379 After processing of the error using I<call_*> is completed,
1380 control reverts back to Perl more or less immediately.
1381
1382 In the diagram, the further right you go the more deeply nested the
1383 scope is.  It is only when control is back with perl on the extreme
1384 left of the diagram that you will have dropped back to the enclosing
1385 scope and any temporaries you have left hanging around will be freed.
1386
1387 In the second example, an event driven program, the flow of control
1388 will be more like this
1389
1390     perl --> XSUB --> event handler
1391                       ...
1392                       event handler --> call_* --> perl
1393                                                        |
1394                       event handler <-- call_* <----+
1395                       ...
1396                       event handler --> call_* --> perl
1397                                                        |
1398                       event handler <-- call_* <----+
1399                       ...
1400                       event handler --> call_* --> perl
1401                                                        |
1402                       event handler <-- call_* <----+
1403
1404 In this case the flow of control can consist of only the repeated
1405 sequence
1406
1407     event handler --> call_* --> perl
1408
1409 for practically the complete duration of the program.  This means that
1410 control may I<never> drop back to the surrounding scope in Perl at the
1411 extreme left.
1412
1413 So what is the big problem? Well, if you are expecting Perl to tidy up
1414 those temporaries for you, you might be in for a long wait.  For Perl
1415 to dispose of your temporaries, control must drop back to the
1416 enclosing scope at some stage.  In the event driven scenario that may
1417 never happen.  This means that, as time goes on, your program will
1418 create more and more temporaries, none of which will ever be freed. As
1419 each of these temporaries consumes some memory your program will
1420 eventually consume all the available memory in your system--kapow!
1421
1422 So here is the bottom line--if you are sure that control will revert
1423 back to the enclosing Perl scope fairly quickly after the end of your
1424 callback, then it isn't absolutely necessary to dispose explicitly of
1425 any temporaries you may have created. Mind you, if you are at all
1426 uncertain about what to do, it doesn't do any harm to tidy up anyway.
1427
1428
1429 =head2 Strategies for Storing Callback Context Information
1430
1431
1432 Potentially one of the trickiest problems to overcome when designing a
1433 callback interface can be figuring out how to store the mapping between
1434 the C callback function and the Perl equivalent.
1435
1436 To help understand why this can be a real problem first consider how a
1437 callback is set up in an all C environment.  Typically a C API will
1438 provide a function to register a callback.  This will expect a pointer
1439 to a function as one of its parameters.  Below is a call to a
1440 hypothetical function C<register_fatal> which registers the C function
1441 to get called when a fatal error occurs.
1442
1443     register_fatal(cb1);
1444
1445 The single parameter C<cb1> is a pointer to a function, so you must
1446 have defined C<cb1> in your code, say something like this
1447
1448     static void
1449     cb1()
1450     {
1451         printf ("Fatal Error\n");
1452         exit(1);
1453     }
1454
1455 Now change that to call a Perl subroutine instead
1456
1457     static SV * callback = (SV*)NULL;
1458
1459     static void
1460     cb1()
1461     {
1462         dSP;
1463
1464         PUSHMARK(SP);
1465
1466         /* Call the Perl sub to process the callback */
1467         call_sv(callback, G_DISCARD);
1468     }
1469
1470
1471     void
1472     register_fatal(fn)
1473         SV *    fn
1474         CODE:
1475         /* Remember the Perl sub */
1476         if (callback == (SV*)NULL)
1477             callback = newSVsv(fn);
1478         else
1479             SvSetSV(callback, fn);
1480
1481         /* register the callback with the external library */
1482         register_fatal(cb1);
1483
1484 where the Perl equivalent of C<register_fatal> and the callback it
1485 registers, C<pcb1>, might look like this
1486
1487     # Register the sub pcb1
1488     register_fatal(\&pcb1);
1489
1490     sub pcb1
1491     {
1492         die "I'm dying...\n";
1493     }
1494
1495 The mapping between the C callback and the Perl equivalent is stored in
1496 the global variable C<callback>.
1497
1498 This will be adequate if you ever need to have only one callback
1499 registered at any time. An example could be an error handler like the
1500 code sketched out above. Remember though, repeated calls to
1501 C<register_fatal> will replace the previously registered callback
1502 function with the new one.
1503
1504 Say for example you want to interface to a library which allows asynchronous
1505 file i/o.  In this case you may be able to register a callback whenever
1506 a read operation has completed. To be of any use we want to be able to
1507 call separate Perl subroutines for each file that is opened.  As it
1508 stands, the error handler example above would not be adequate as it
1509 allows only a single callback to be defined at any time. What we
1510 require is a means of storing the mapping between the opened file and
1511 the Perl subroutine we want to be called for that file.
1512
1513 Say the i/o library has a function C<asynch_read> which associates a C
1514 function C<ProcessRead> with a file handle C<fh>--this assumes that it
1515 has also provided some routine to open the file and so obtain the file
1516 handle.
1517
1518     asynch_read(fh, ProcessRead)
1519
1520 This may expect the C I<ProcessRead> function of this form
1521
1522     void
1523     ProcessRead(fh, buffer)
1524     int fh;
1525     char *      buffer;
1526     {
1527          ...
1528     }
1529
1530 To provide a Perl interface to this library we need to be able to map
1531 between the C<fh> parameter and the Perl subroutine we want called.  A
1532 hash is a convenient mechanism for storing this mapping.  The code
1533 below shows a possible implementation
1534
1535     static HV * Mapping = (HV*)NULL;
1536
1537     void
1538     asynch_read(fh, callback)
1539         int     fh
1540         SV *    callback
1541         CODE:
1542         /* If the hash doesn't already exist, create it */
1543         if (Mapping == (HV*)NULL)
1544             Mapping = newHV();
1545
1546         /* Save the fh -> callback mapping */
1547         hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
1548
1549         /* Register with the C Library */
1550         asynch_read(fh, asynch_read_if);
1551
1552 and C<asynch_read_if> could look like this
1553
1554     static void
1555     asynch_read_if(fh, buffer)
1556     int fh;
1557     char *      buffer;
1558     {
1559         dSP;
1560         SV ** sv;
1561
1562         /* Get the callback associated with fh */
1563         sv =  hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
1564         if (sv == (SV**)NULL)
1565             croak("Internal error...\n");
1566
1567         PUSHMARK(SP);
1568         XPUSHs(sv_2mortal(newSViv(fh)));
1569         XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
1570         PUTBACK;
1571
1572         /* Call the Perl sub */
1573         call_sv(*sv, G_DISCARD);
1574     }
1575
1576 For completeness, here is C<asynch_close>.  This shows how to remove
1577 the entry from the hash C<Mapping>.
1578
1579     void
1580     asynch_close(fh)
1581         int     fh
1582         CODE:
1583         /* Remove the entry from the hash */
1584         (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
1585
1586         /* Now call the real asynch_close */
1587         asynch_close(fh);
1588
1589 So the Perl interface would look like this
1590
1591     sub callback1
1592     {
1593         my($handle, $buffer) = @_;
1594     }
1595
1596     # Register the Perl callback
1597     asynch_read($fh, \&callback1);
1598
1599     asynch_close($fh);
1600
1601 The mapping between the C callback and Perl is stored in the global
1602 hash C<Mapping> this time. Using a hash has the distinct advantage that
1603 it allows an unlimited number of callbacks to be registered.
1604
1605 What if the interface provided by the C callback doesn't contain a
1606 parameter which allows the file handle to Perl subroutine mapping?  Say
1607 in the asynchronous i/o package, the callback function gets passed only
1608 the C<buffer> parameter like this
1609
1610     void
1611     ProcessRead(buffer)
1612     char *      buffer;
1613     {
1614         ...
1615     }
1616
1617 Without the file handle there is no straightforward way to map from the
1618 C callback to the Perl subroutine.
1619
1620 In this case a possible way around this problem is to predefine a
1621 series of C functions to act as the interface to Perl, thus
1622
1623     #define MAX_CB              3
1624     #define NULL_HANDLE -1
1625     typedef void (*FnMap)();
1626
1627     struct MapStruct {
1628         FnMap    Function;
1629         SV *     PerlSub;
1630         int      Handle;
1631       };
1632
1633     static void  fn1();
1634     static void  fn2();
1635     static void  fn3();
1636
1637     static struct MapStruct Map [MAX_CB] =
1638         {
1639             { fn1, NULL, NULL_HANDLE },
1640             { fn2, NULL, NULL_HANDLE },
1641             { fn3, NULL, NULL_HANDLE }
1642         };
1643
1644     static void
1645     Pcb(index, buffer)
1646     int index;
1647     char * buffer;
1648     {
1649         dSP;
1650
1651         PUSHMARK(SP);
1652         XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
1653         PUTBACK;
1654
1655         /* Call the Perl sub */
1656         call_sv(Map[index].PerlSub, G_DISCARD);
1657     }
1658
1659     static void
1660     fn1(buffer)
1661     char * buffer;
1662     {
1663         Pcb(0, buffer);
1664     }
1665
1666     static void
1667     fn2(buffer)
1668     char * buffer;
1669     {
1670         Pcb(1, buffer);
1671     }
1672
1673     static void
1674     fn3(buffer)
1675     char * buffer;
1676     {
1677         Pcb(2, buffer);
1678     }
1679
1680     void
1681     array_asynch_read(fh, callback)
1682         int             fh
1683         SV *    callback
1684         CODE:
1685         int index;
1686         int null_index = MAX_CB;
1687
1688         /* Find the same handle or an empty entry */
1689         for (index = 0; index < MAX_CB; ++index)
1690         {
1691             if (Map[index].Handle == fh)
1692                 break;
1693
1694             if (Map[index].Handle == NULL_HANDLE)
1695                 null_index = index;
1696         }
1697
1698         if (index == MAX_CB && null_index == MAX_CB)
1699             croak ("Too many callback functions registered\n");
1700
1701         if (index == MAX_CB)
1702             index = null_index;
1703
1704         /* Save the file handle */
1705         Map[index].Handle = fh;
1706
1707         /* Remember the Perl sub */
1708         if (Map[index].PerlSub == (SV*)NULL)
1709             Map[index].PerlSub = newSVsv(callback);
1710         else
1711             SvSetSV(Map[index].PerlSub, callback);
1712
1713         asynch_read(fh, Map[index].Function);
1714
1715     void
1716     array_asynch_close(fh)
1717         int     fh
1718         CODE:
1719         int index;
1720
1721         /* Find the file handle */
1722         for (index = 0; index < MAX_CB; ++ index)
1723             if (Map[index].Handle == fh)
1724                 break;
1725
1726         if (index == MAX_CB)
1727             croak ("could not close fh %d\n", fh);
1728
1729         Map[index].Handle = NULL_HANDLE;
1730         SvREFCNT_dec(Map[index].PerlSub);
1731         Map[index].PerlSub = (SV*)NULL;
1732
1733         asynch_close(fh);
1734
1735 In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to
1736 remember the Perl subroutine to be called. Each of the functions holds
1737 a separate hard-wired index which is used in the function C<Pcb> to
1738 access the C<Map> array and actually call the Perl subroutine.
1739
1740 There are some obvious disadvantages with this technique.
1741
1742 Firstly, the code is considerably more complex than with the previous
1743 example.
1744
1745 Secondly, there is a hard-wired limit (in this case 3) to the number of
1746 callbacks that can exist simultaneously. The only way to increase the
1747 limit is by modifying the code to add more functions and then
1748 recompiling.  None the less, as long as the number of functions is
1749 chosen with some care, it is still a workable solution and in some
1750 cases is the only one available.
1751
1752 To summarize, here are a number of possible methods for you to consider
1753 for storing the mapping between C and the Perl callback
1754
1755 =over 5
1756
1757 =item 1. Ignore the problem - Allow only 1 callback
1758
1759 For a lot of situations, like interfacing to an error handler, this may
1760 be a perfectly adequate solution.
1761
1762 =item 2. Create a sequence of callbacks - hard wired limit
1763
1764 If it is impossible to tell from the parameters passed back from the C
1765 callback what the context is, then you may need to create a sequence of C
1766 callback interface functions, and store pointers to each in an array.
1767
1768 =item 3. Use a parameter to map to the Perl callback
1769
1770 A hash is an ideal mechanism to store the mapping between C and Perl.
1771
1772 =back
1773
1774
1775 =head2 Alternate Stack Manipulation
1776
1777
1778 Although I have made use of only the C<POP*> macros to access values
1779 returned from Perl subroutines, it is also possible to bypass these
1780 macros and read the stack using the C<ST> macro (See L<perlxs> for a
1781 full description of the C<ST> macro).
1782
1783 Most of the time the C<POP*> macros should be adequate; the main
1784 problem with them is that they force you to process the returned values
1785 in sequence. This may not be the most suitable way to process the
1786 values in some cases. What we want is to be able to access the stack in
1787 a random order. The C<ST> macro as used when coding an XSUB is ideal
1788 for this purpose.
1789
1790 The code below is the example given in the section I<Returning a List
1791 of Values> recoded to use C<ST> instead of C<POP*>.
1792
1793     static void
1794     call_AddSubtract2(a, b)
1795     int a;
1796     int b;
1797     {
1798         dSP;
1799         I32 ax;
1800         int count;
1801
1802         ENTER;
1803         SAVETMPS;
1804
1805         PUSHMARK(SP);
1806         XPUSHs(sv_2mortal(newSViv(a)));
1807         XPUSHs(sv_2mortal(newSViv(b)));
1808         PUTBACK;
1809
1810         count = call_pv("AddSubtract", G_ARRAY);
1811
1812         SPAGAIN;
1813         SP -= count;
1814         ax = (SP - PL_stack_base) + 1;
1815
1816         if (count != 2)
1817             croak("Big trouble\n");
1818
1819         printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
1820         printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));
1821
1822         PUTBACK;
1823         FREETMPS;
1824         LEAVE;
1825     }
1826
1827 Notes
1828
1829 =over 5
1830
1831 =item 1.
1832
1833 Notice that it was necessary to define the variable C<ax>.  This is
1834 because the C<ST> macro expects it to exist.  If we were in an XSUB it
1835 would not be necessary to define C<ax> as it is already defined for
1836 us.
1837
1838 =item 2.
1839
1840 The code
1841
1842         SPAGAIN;
1843         SP -= count;
1844         ax = (SP - PL_stack_base) + 1;
1845
1846 sets the stack up so that we can use the C<ST> macro.
1847
1848 =item 3.
1849
1850 Unlike the original coding of this example, the returned
1851 values are not accessed in reverse order.  So C<ST(0)> refers to the
1852 first value returned by the Perl subroutine and C<ST(count-1)>
1853 refers to the last.
1854
1855 =back
1856
1857 =head2 Creating and Calling an Anonymous Subroutine in C
1858
1859 As we've already shown, C<call_sv> can be used to invoke an
1860 anonymous subroutine.  However, our example showed a Perl script
1861 invoking an XSUB to perform this operation.  Let's see how it can be
1862 done inside our C code:
1863
1864  ...
1865
1866  SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);
1867
1868  ...
1869
1870  call_sv(cvrv, G_VOID|G_NOARGS);
1871
1872 C<eval_pv> is used to compile the anonymous subroutine, which
1873 will be the return value as well (read more about C<eval_pv> in
1874 L<perlapi/eval_pv>).  Once this code reference is in hand, it
1875 can be mixed in with all the previous examples we've shown.
1876
1877 =head1 LIGHTWEIGHT CALLBACKS
1878
1879 Sometimes you need to invoke the same subroutine repeatedly.
1880 This usually happens with a function that acts on a list of
1881 values, such as Perl's built-in sort(). You can pass a
1882 comparison function to sort(), which will then be invoked
1883 for every pair of values that needs to be compared. The first()
1884 and reduce() functions from L<List::Util> follow a similar
1885 pattern.
1886
1887 In this case it is possible to speed up the routine (often
1888 quite substantially) by using the lightweight callback API.
1889 The idea is that the calling context only needs to be
1890 created and destroyed once, and the sub can be called
1891 arbitrarily many times in between.
1892
1893 It is usual to pass parameters using global variables (typically
1894 $_ for one parameter, or $a and $b for two parameters) rather
1895 than via @_. (It is possible to use the @_ mechanism if you know
1896 what you're doing, though there is as yet no supported API for
1897 it. It's also inherently slower.)
1898
1899 The pattern of macro calls is like this:
1900
1901     dMULTICALL;                 /* Declare local variables */
1902     I32 gimme = G_SCALAR;       /* context of the call: G_SCALAR,
1903                                  * G_ARRAY, or G_VOID */
1904
1905     PUSH_MULTICALL(cv);         /* Set up the context for calling cv,
1906                                    and set local vars appropriately */
1907
1908     /* loop */ {
1909         /* set the value(s) af your parameter variables */
1910         MULTICALL;              /* Make the actual call */
1911     } /* end of loop */
1912
1913     POP_MULTICALL;              /* Tear down the calling context */
1914
1915 For some concrete examples, see the implementation of the
1916 first() and reduce() functions of List::Util 1.18. There you
1917 will also find a header file that emulates the multicall API
1918 on older versions of perl.
1919
1920 =head1 SEE ALSO
1921
1922 L<perlxs>, L<perlguts>, L<perlembed>
1923
1924 =head1 AUTHOR
1925
1926 Paul Marquess 
1927
1928 Special thanks to the following people who assisted in the creation of
1929 the document.
1930
1931 Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
1932 and Larry Wall.
1933
1934 =head1 DATE
1935
1936 Version 1.3, 14th Apr 1997