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