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