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