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