Integrate perlio:
[p5sagit/p5-mst-13.2.git] / pod / perlcall.pod
CommitLineData
a0d0e21e 1=head1 NAME
2
3perlcall - Perl calling conventions from C
4
5=head1 DESCRIPTION
6
d1b91892 7The purpose of this document is to show you how to call Perl subroutines
5f05dabc 8directly from C, i.e., how to write I<callbacks>.
a0d0e21e 9
d1b91892 10Apart from discussing the C interface provided by Perl for writing
11callbacks the document uses a series of examples to show how the
12interface actually works in practice. In addition some techniques for
13coding callbacks are covered.
a0d0e21e 14
d1b91892 15Examples where callbacks are necessary include
a0d0e21e 16
17=over 5
18
d1b91892 19=item * An Error Handler
a0d0e21e 20
21You have created an XSUB interface to an application's C API.
22
23A fairly common feature in applications is to allow you to define a C
d1b91892 24function that will be called whenever something nasty occurs. What we
25would like is to be able to specify a Perl subroutine that will be
26called instead.
a0d0e21e 27
d1b91892 28=item * An Event Driven Program
a0d0e21e 29
d1b91892 30The classic example of where callbacks are used is when writing an
31event driven program like for an X windows application. In this case
184e9718 32you register functions to be called whenever specific events occur,
5f05dabc 33e.g., a mouse button is pressed, the cursor moves into a window or a
d1b91892 34menu item is selected.
a0d0e21e 35
36=back
37
d1b91892 38Although the techniques described here are applicable when embedding
39Perl in a C program, this is not the primary goal of this document.
40There are other details that must be considered and are specific to
41embedding Perl. For details on embedding Perl in C refer to
42L<perlembed>.
a0d0e21e 43
d1b91892 44Before you launch yourself head first into the rest of this document,
45it would be a good idea to have read the following two documents -
8e07c86e 46L<perlxs> and L<perlguts>.
a0d0e21e 47
4929bf7b 48=head1 THE CALL_ FUNCTIONS
a0d0e21e 49
d1b91892 50Although this stuff is easier to explain using examples, you first need
51be aware of a few important definitions.
a0d0e21e 52
d1b91892 53Perl has a number of C functions that allow you to call Perl
54subroutines. They are
a0d0e21e 55
4929bf7b 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) ;
a0d0e21e 60
4929bf7b 61The key function is I<call_sv>. All the other functions are
d1b91892 62fairly simple wrappers which make it easier to call Perl subroutines in
4929bf7b 63special cases. At the end of the day they will all call I<call_sv>
5f05dabc 64to invoke the Perl subroutine.
d1b91892 65
4929bf7b 66All the I<call_*> functions have a C<flags> parameter which is
d1b91892 67used to pass a bit mask of options to Perl. This bit mask operates
68identically for each of the functions. The settings available in the
69bit mask are discussed in L<FLAG VALUES>.
70
71Each of the functions will now be discussed in turn.
72
73=over 5
74
4929bf7b 75=item call_sv
d1b91892 76
4929bf7b 77I<call_sv> takes two parameters, the first, C<sv>, is an SV*.
d1b91892 78This allows you to specify the Perl subroutine to be called either as a
79C string (which has first been converted to an SV) or a reference to a
4929bf7b 80subroutine. The section, I<Using call_sv>, shows how you can make
81use of I<call_sv>.
d1b91892 82
4929bf7b 83=item call_pv
d1b91892 84
4929bf7b 85The function, I<call_pv>, is similar to I<call_sv> except it
d1b91892 86expects its first parameter to be a C char* which identifies the Perl
4929bf7b 87subroutine you want to call, e.g., C<call_pv("fred", 0)>. If the
d1b91892 88subroutine you want to call is in another package, just include the
5f05dabc 89package name in the string, e.g., C<"pkg::fred">.
d1b91892 90
4929bf7b 91=item call_method
d1b91892 92
4929bf7b 93The function I<call_method> is used to call a method from a Perl
d1b91892 94class. The parameter C<methname> corresponds to the name of the method
95to be called. Note that the class that the method belongs to is passed
96on the Perl stack rather than in the parameter list. This class can be
97either the name of the class (for a static method) or a reference to an
98object (for a virtual method). See L<perlobj> for more information on
4929bf7b 99static and virtual methods and L<Using call_method> for an example
100of using I<call_method>.
d1b91892 101
4929bf7b 102=item call_argv
d1b91892 103
4929bf7b 104I<call_argv> calls the Perl subroutine specified by the C string
d1b91892 105stored in the C<subname> parameter. It also takes the usual C<flags>
106parameter. The final parameter, C<argv>, consists of a NULL terminated
107list of C strings to be passed as parameters to the Perl subroutine.
4929bf7b 108See I<Using call_argv>.
d1b91892 109
110=back
111
112All the functions return an integer. This is a count of the number of
113items returned by the Perl subroutine. The actual items returned by the
114subroutine are stored on the Perl stack.
115
116As a general rule you should I<always> check the return value from
117these functions. Even if you are expecting only a particular number of
118values to be returned from the Perl subroutine, there is nothing to
19799a22 119stop someone from doing something unexpected--don't say you haven't
d1b91892 120been warned.
121
122=head1 FLAG VALUES
123
4929bf7b 124The C<flags> parameter in all the I<call_*> functions is a bit mask
d1b91892 125which can consist of any combination of the symbols defined below,
126OR'ed together.
127
128
54310121 129=head2 G_VOID
130
131Calls the Perl subroutine in a void context.
132
133This flag has 2 effects:
134
135=over 5
136
137=item 1.
138
139It indicates to the subroutine being called that it is executing in
140a void context (if it executes I<wantarray> the result will be the
141undefined value).
142
143=item 2.
144
145It ensures that nothing is actually returned from the subroutine.
146
147=back
148
4929bf7b 149The value returned by the I<call_*> function indicates how many
54310121 150items have been returned by the Perl subroutine - in this case it will
151be 0.
152
153
d1b91892 154=head2 G_SCALAR
155
156Calls the Perl subroutine in a scalar context. This is the default
4929bf7b 157context flag setting for all the I<call_*> functions.
d1b91892 158
184e9718 159This flag has 2 effects:
d1b91892 160
161=over 5
162
163=item 1.
164
184e9718 165It indicates to the subroutine being called that it is executing in a
d1b91892 166scalar context (if it executes I<wantarray> the result will be false).
a0d0e21e 167
d1b91892 168=item 2.
169
184e9718 170It ensures that only a scalar is actually returned from the subroutine.
d1b91892 171The subroutine can, of course, ignore the I<wantarray> and return a
172list anyway. If so, then only the last element of the list will be
173returned.
174
175=back
176
4929bf7b 177The value returned by the I<call_*> function indicates how many
d1b91892 178items have been returned by the Perl subroutine - in this case it will
179be either 0 or 1.
a0d0e21e 180
d1b91892 181If 0, then you have specified the G_DISCARD flag.
a0d0e21e 182
d1b91892 183If 1, then the item actually returned by the Perl subroutine will be
184stored on the Perl stack - the section I<Returning a Scalar> shows how
185to access this value on the stack. Remember that regardless of how
186many items the Perl subroutine returns, only the last one will be
187accessible from the stack - think of the case where only one value is
188returned as being a list with only one element. Any other items that
189were returned will not exist by the time control returns from the
4929bf7b 190I<call_*> function. The section I<Returning a list in a scalar
54310121 191context> shows an example of this behavior.
a0d0e21e 192
a0d0e21e 193
d1b91892 194=head2 G_ARRAY
a0d0e21e 195
d1b91892 196Calls the Perl subroutine in a list context.
a0d0e21e 197
184e9718 198As with G_SCALAR, this flag has 2 effects:
a0d0e21e 199
200=over 5
201
d1b91892 202=item 1.
203
90fdbbb7 204It indicates to the subroutine being called that it is executing in a
205list context (if it executes I<wantarray> the result will be true).
a0d0e21e 206
a0d0e21e 207
d1b91892 208=item 2.
a0d0e21e 209
184e9718 210It ensures that all items returned from the subroutine will be
4929bf7b 211accessible when control returns from the I<call_*> function.
a0d0e21e 212
d1b91892 213=back
a0d0e21e 214
4929bf7b 215The value returned by the I<call_*> function indicates how many
d1b91892 216items have been returned by the Perl subroutine.
a0d0e21e 217
184e9718 218If 0, then you have specified the G_DISCARD flag.
a0d0e21e 219
d1b91892 220If not 0, then it will be a count of the number of items returned by
221the subroutine. These items will be stored on the Perl stack. The
222section I<Returning a list of values> gives an example of using the
223G_ARRAY flag and the mechanics of accessing the returned items from the
224Perl stack.
a0d0e21e 225
d1b91892 226=head2 G_DISCARD
a0d0e21e 227
4929bf7b 228By default, the I<call_*> functions place the items returned from
d1b91892 229by the Perl subroutine on the stack. If you are not interested in
230these items, then setting this flag will make Perl get rid of them
231automatically for you. Note that it is still possible to indicate a
232context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
a0d0e21e 233
d1b91892 234If you do not set this flag then it is I<very> important that you make
5f05dabc 235sure that any temporaries (i.e., parameters passed to the Perl
d1b91892 236subroutine and values returned from the subroutine) are disposed of
237yourself. The section I<Returning a Scalar> gives details of how to
5f05dabc 238dispose of these temporaries explicitly and the section I<Using Perl to
d1b91892 239dispose of temporaries> discusses the specific circumstances where you
240can ignore the problem and let Perl deal with it for you.
a0d0e21e 241
d1b91892 242=head2 G_NOARGS
a0d0e21e 243
4929bf7b 244Whenever a Perl subroutine is called using one of the I<call_*>
d1b91892 245functions, it is assumed by default that parameters are to be passed to
246the subroutine. If you are not passing any parameters to the Perl
247subroutine, you can save a bit of time by setting this flag. It has
248the effect of not creating the C<@_> array for the Perl subroutine.
a0d0e21e 249
d1b91892 250Although the functionality provided by this flag may seem
251straightforward, it should be used only if there is a good reason to do
252so. The reason for being cautious is that even if you have specified
253the G_NOARGS flag, it is still possible for the Perl subroutine that
254has been called to think that you have passed it parameters.
a0d0e21e 255
d1b91892 256In fact, what can happen is that the Perl subroutine you have called
257can access the C<@_> array from a previous Perl subroutine. This will
4929bf7b 258occur when the code that is executing the I<call_*> function has
d1b91892 259itself been called from another Perl subroutine. The code below
260illustrates this
a0d0e21e 261
84f709e7 262 sub fred
263 { print "@_\n" }
a0d0e21e 264
84f709e7 265 sub joe
266 { &fred }
a0d0e21e 267
84f709e7 268 &joe(1,2,3) ;
a0d0e21e 269
270This will print
271
d1b91892 272 1 2 3
273
274What has happened is that C<fred> accesses the C<@_> array which
275belongs to C<joe>.
a0d0e21e 276
a0d0e21e 277
54310121 278=head2 G_EVAL
a0d0e21e 279
d1b91892 280It is possible for the Perl subroutine you are calling to terminate
5f05dabc 281abnormally, e.g., by calling I<die> explicitly or by not actually
268118b2 282existing. By default, when either of these events occurs, the
283process will terminate immediately. If you want to trap this
d1b91892 284type of event, specify the G_EVAL flag. It will put an I<eval { }>
285around the subroutine call.
a0d0e21e 286
4929bf7b 287Whenever control returns from the I<call_*> function you need to
d1b91892 288check the C<$@> variable as you would in a normal Perl script.
289
4929bf7b 290The value returned from the I<call_*> function is dependent on
d1b91892 291what other flags have been specified and whether an error has
184e9718 292occurred. Here are all the different cases that can occur:
d1b91892 293
294=over 5
295
296=item *
297
4929bf7b 298If the I<call_*> function returns normally, then the value
d1b91892 299returned is as specified in the previous sections.
300
301=item *
302
303If G_DISCARD is specified, the return value will always be 0.
304
305=item *
306
307If G_ARRAY is specified I<and> an error has occurred, the return value
308will always be 0.
309
310=item *
a0d0e21e 311
d1b91892 312If G_SCALAR is specified I<and> an error has occurred, the return value
313will be 1 and the value on the top of the stack will be I<undef>. This
314means that if you have already detected the error by checking C<$@> and
315you want the program to continue, you must remember to pop the I<undef>
316from the stack.
a0d0e21e 317
318=back
319
54310121 320See I<Using G_EVAL> for details on using G_EVAL.
d1b91892 321
c07a80fd 322=head2 G_KEEPERR
323
324You may have noticed that using the G_EVAL flag described above will
325B<always> clear the C<$@> variable and set it to a string describing
326the error iff there was an error in the called code. This unqualified
327resetting of C<$@> can be problematic in the reliable identification of
328errors using the C<eval {}> mechanism, because the possibility exists
329that perl will call other code (end of block processing code, for
330example) between the time the error causes C<$@> to be set within
331C<eval {}>, and the subsequent statement which checks for the value of
332C<$@> gets executed in the user's script.
333
334This scenario will mostly be applicable to code that is meant to be
335called from within destructors, asynchronous callbacks, signal
336handlers, C<__DIE__> or C<__WARN__> hooks, and C<tie> functions. In
337such situations, you will not want to clear C<$@> at all, but simply to
338append any new errors to any existing value of C<$@>.
339
340The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
4929bf7b 341I<call_*> functions that are used to implement such code. This flag
c07a80fd 342has no effect when G_EVAL is not used.
343
344When G_KEEPERR is used, any errors in the called code will be prefixed
345with the string "\t(in cleanup)", and appended to the current value
346of C<$@>.
347
348The G_KEEPERR flag was introduced in Perl version 5.002.
349
350See I<Using G_KEEPERR> for an example of a situation that warrants the
351use of this flag.
352
54310121 353=head2 Determining the Context
d1b91892 354
355As mentioned above, you can determine the context of the currently
54310121 356executing subroutine in Perl with I<wantarray>. The equivalent test
357can be made in C by using the C<GIMME_V> macro, which returns
90fdbbb7 358C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
7a2e2cd6 359in a scalar context, or C<G_VOID> if in a void context (i.e. the
54310121 360return value will not be used). An older version of this macro is
361called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
362C<G_VOID>. An example of using the C<GIMME_V> macro is shown in
363section I<Using GIMME_V>.
d1b91892 364
365=head1 KNOWN PROBLEMS
366
367This section outlines all known problems that exist in the
4929bf7b 368I<call_*> functions.
d1b91892 369
370=over 5
371
372=item 1.
373
374If you are intending to make use of both the G_EVAL and G_SCALAR flags
375in your code, use a version of Perl greater than 5.000. There is a bug
376in version 5.000 of Perl which means that the combination of these two
377flags will not work as described in the section I<FLAG VALUES>.
378
379Specifically, if the two flags are used when calling a subroutine and
380that subroutine does not call I<die>, the value returned by
4929bf7b 381I<call_*> will be wrong.
d1b91892 382
383
384=item 2.
385
4929bf7b 386In Perl 5.000 and 5.001 there is a problem with using I<call_*> if
d1b91892 387the Perl sub you are calling attempts to trap a I<die>.
388
389The symptom of this problem is that the called Perl sub will continue
390to completion, but whenever it attempts to pass control back to the
391XSUB, the program will immediately terminate.
392
393For example, say you want to call this Perl sub
394
84f709e7 395 sub fred
396 {
397 eval { die "Fatal Error" ; }
398 print "Trapped error: $@\n"
399 if $@ ;
d1b91892 400 }
401
402via this XSUB
403
404 void
405 Call_fred()
406 CODE:
924508f0 407 PUSHMARK(SP) ;
4929bf7b 408 call_pv("fred", G_DISCARD|G_NOARGS) ;
d1b91892 409 fprintf(stderr, "back in Call_fred\n") ;
410
411When C<Call_fred> is executed it will print
412
413 Trapped error: Fatal Error
414
415As control never returns to C<Call_fred>, the C<"back in Call_fred">
416string will not get printed.
417
3fe9a6f1 418To work around this problem, you can either upgrade to Perl 5.002 or
4929bf7b 419higher, or use the G_EVAL flag with I<call_*> as shown below
d1b91892 420
421 void
422 Call_fred()
423 CODE:
924508f0 424 PUSHMARK(SP) ;
4929bf7b 425 call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ;
d1b91892 426 fprintf(stderr, "back in Call_fred\n") ;
427
428=back
429
430
a0d0e21e 431
432=head1 EXAMPLES
433
434Enough of the definition talk, let's have a few examples.
435
d1b91892 436Perl provides many macros to assist in accessing the Perl stack.
437Wherever possible, these macros should always be used when interfacing
5f05dabc 438to Perl internals. We hope this should make the code less vulnerable
d1b91892 439to any changes made to Perl in the future.
a0d0e21e 440
d1b91892 441Another point worth noting is that in the first series of examples I
4929bf7b 442have made use of only the I<call_pv> function. This has been done
d1b91892 443to keep the code simpler and ease you into the topic. Wherever
4929bf7b 444possible, if the choice is between using I<call_pv> and
445I<call_sv>, you should always try to use I<call_sv>. See
446I<Using call_sv> for details.
a0d0e21e 447
d1b91892 448=head2 No Parameters, Nothing returned
a0d0e21e 449
d1b91892 450This first trivial example will call a Perl subroutine, I<PrintUID>, to
451print out the UID of the process.
a0d0e21e 452
84f709e7 453 sub PrintUID
454 {
455 print "UID is $<\n" ;
a0d0e21e 456 }
457
d1b91892 458and here is a C function to call it
a0d0e21e 459
d1b91892 460 static void
a0d0e21e 461 call_PrintUID()
462 {
d1b91892 463 dSP ;
a0d0e21e 464
924508f0 465 PUSHMARK(SP) ;
4929bf7b 466 call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
a0d0e21e 467 }
468
d1b91892 469Simple, eh.
a0d0e21e 470
d1b91892 471A few points to note about this example.
a0d0e21e 472
473=over 5
474
d1b91892 475=item 1.
a0d0e21e 476
924508f0 477Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
d1b91892 478the next example.
a0d0e21e 479
480=item 2.
481
d1b91892 482We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
483specified.
a0d0e21e 484
d1b91892 485=item 3.
a0d0e21e 486
487We aren't interested in anything returned from I<PrintUID>, so
5f05dabc 488G_DISCARD is specified. Even if I<PrintUID> was changed to
a0d0e21e 489return some value(s), having specified G_DISCARD will mean that they
4929bf7b 490will be wiped by the time control returns from I<call_pv>.
a0d0e21e 491
d1b91892 492=item 4.
a0d0e21e 493
4929bf7b 494As I<call_pv> is being used, the Perl subroutine is specified as a
d1b91892 495C string. In this case the subroutine name has been 'hard-wired' into the
496code.
a0d0e21e 497
498=item 5.
499
d1b91892 500Because we specified G_DISCARD, it is not necessary to check the value
4929bf7b 501returned from I<call_pv>. It will always be 0.
a0d0e21e 502
503=back
504
d1b91892 505=head2 Passing Parameters
a0d0e21e 506
d1b91892 507Now let's make a slightly more complex example. This time we want to
19799a22 508call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
509string ($s) and an integer ($n). The subroutine will simply
510print the first $n characters of the string.
a0d0e21e 511
d1b91892 512So the Perl subroutine would look like this
a0d0e21e 513
84f709e7 514 sub LeftString
515 {
516 my($s, $n) = @_ ;
517 print substr($s, 0, $n), "\n" ;
a0d0e21e 518 }
519
520The 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
9b6570b4 529 ENTER ;
530 SAVETMPS ;
531
924508f0 532 PUSHMARK(SP) ;
a0d0e21e 533 XPUSHs(sv_2mortal(newSVpv(a, 0)));
534 XPUSHs(sv_2mortal(newSViv(b)));
535 PUTBACK ;
536
4929bf7b 537 call_pv("LeftString", G_DISCARD);
9b6570b4 538
539 FREETMPS ;
540 LEAVE ;
a0d0e21e 541 }
542
a0d0e21e 543Here are a few notes on the C function I<call_LeftString>.
544
545=over 5
546
d1b91892 547=item 1.
a0d0e21e 548
d1b91892 549Parameters are passed to the Perl subroutine using the Perl stack.
550This is the purpose of the code beginning with the line C<dSP> and
1e62ac33 551ending with the line C<PUTBACK>. The C<dSP> declares a local copy
924508f0 552of the stack pointer. This local copy should B<always> be accessed
553as C<SP>.
a0d0e21e 554
d1b91892 555=item 2.
a0d0e21e 556
557If you are going to put something onto the Perl stack, you need to know
19799a22 558where to put it. This is the purpose of the macro C<dSP>--it declares
d1b91892 559and initializes a I<local> copy of the Perl stack pointer.
a0d0e21e 560
561All the other macros which will be used in this example require you to
d1b91892 562have used this macro.
a0d0e21e 563
d1b91892 564The exception to this rule is if you are calling a Perl subroutine
565directly from an XSUB function. In this case it is not necessary to
19799a22 566use the C<dSP> macro explicitly--it will be declared for you
d1b91892 567automatically.
a0d0e21e 568
d1b91892 569=item 3.
a0d0e21e 570
571Any parameters to be pushed onto the stack should be bracketed by the
d1b91892 572C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
5f05dabc 573this context, is to count the number of parameters you are
574pushing automatically. Then whenever Perl is creating the C<@_> array for the
d1b91892 575subroutine, it knows how big to make it.
576
577The C<PUSHMARK> macro tells Perl to make a mental note of the current
578stack pointer. Even if you aren't passing any parameters (like the
579example shown in the section I<No Parameters, Nothing returned>) you
580must still call the C<PUSHMARK> macro before you can call any of the
4929bf7b 581I<call_*> functions--Perl still needs to know that there are no
d1b91892 582parameters.
583
584The C<PUTBACK> macro sets the global copy of the stack pointer to be
4929bf7b 585the same as our local copy. If we didn't do this I<call_pv>
19799a22 586wouldn't know where the two parameters we pushed were--remember that
d1b91892 587up to now all the stack pointer manipulation we have done is with our
588local copy, I<not> the global copy.
589
590=item 4.
591
a0d0e21e 592Next, we come to XPUSHs. This is where the parameters actually get
d1b91892 593pushed onto the stack. In this case we are pushing a string and an
594integer.
a0d0e21e 595
54310121 596See L<perlguts/"XSUBs and the Argument Stack"> for details
d1b91892 597on how the XPUSH macros work.
a0d0e21e 598
087fe227 599=item 5.
a0d0e21e 600
9b6570b4 601Because we created temporary values (by means of sv_2mortal() calls)
602we will have to tidy up the Perl stack and dispose of mortal SVs.
603
604This is the purpose of
605
606 ENTER ;
607 SAVETMPS ;
608
609at the start of the function, and
610
611 FREETMPS ;
612 LEAVE ;
613
614at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
615temporaries we create. This means that the temporaries we get rid of
616will be limited to those which were created after these calls.
617
618The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
619the Perl subroutine (see next example), plus it will also dump the
620mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the
621beginning of the code makes sure that no other mortals are destroyed.
622
623Think of these macros as working a bit like using C<{> and C<}> in Perl
624to limit the scope of local variables.
625
626See the section I<Using Perl to dispose of temporaries> for details of
627an alternative to using these macros.
628
087fe227 629=item 6.
9b6570b4 630
087fe227 631Finally, I<LeftString> can now be called via the I<call_pv> function.
632The only flag specified this time is G_DISCARD. Because we are passing
6332 parameters to the Perl subroutine this time, we have not specified
634G_NOARGS.
a0d0e21e 635
636=back
637
d1b91892 638=head2 Returning a Scalar
a0d0e21e 639
d1b91892 640Now for an example of dealing with the items returned from a Perl
641subroutine.
a0d0e21e 642
5f05dabc 643Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
d1b91892 644and simply returns their sum.
a0d0e21e 645
84f709e7 646 sub Adder
647 {
648 my($a, $b) = @_ ;
649 $a + $b ;
a0d0e21e 650 }
651
5f05dabc 652Because we are now concerned with the return value from I<Adder>, the C
d1b91892 653function required to call it is now a bit more complex.
a0d0e21e 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
924508f0 666 PUSHMARK(SP) ;
a0d0e21e 667 XPUSHs(sv_2mortal(newSViv(a)));
668 XPUSHs(sv_2mortal(newSViv(b)));
669 PUTBACK ;
670
4929bf7b 671 count = call_pv("Adder", G_SCALAR);
a0d0e21e 672
673 SPAGAIN ;
674
d1b91892 675 if (count != 1)
676 croak("Big trouble\n") ;
a0d0e21e 677
d1b91892 678 printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
a0d0e21e 679
680 PUTBACK ;
681 FREETMPS ;
682 LEAVE ;
683 }
684
a0d0e21e 685Points to note this time are
686
687=over 5
688
54310121 689=item 1.
a0d0e21e 690
d1b91892 691The only flag specified this time was G_SCALAR. That means the C<@_>
692array will be created and that the value returned by I<Adder> will
4929bf7b 693still exist after the call to I<call_pv>.
a0d0e21e 694
a0d0e21e 695=item 2.
696
a0d0e21e 697The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
698stack pointer. This is necessary because it is possible that the memory
68dc0745 699allocated to the Perl stack has been reallocated whilst in the
4929bf7b 700I<call_pv> call.
a0d0e21e 701
d1b91892 702If you are making use of the Perl stack pointer in your code you must
54310121 703always refresh the local copy using SPAGAIN whenever you make use
4929bf7b 704of the I<call_*> functions or any other Perl internal function.
a0d0e21e 705
9b6570b4 706=item 3.
a0d0e21e 707
d1b91892 708Although only a single value was expected to be returned from I<Adder>,
4929bf7b 709it is still good practice to check the return code from I<call_pv>
d1b91892 710anyway.
a0d0e21e 711
d1b91892 712Expecting a single value is not quite the same as knowing that there
713will be one. If someone modified I<Adder> to return a list and we
714didn't check for that possibility and take appropriate action the Perl
715stack would end up in an inconsistent state. That is something you
5f05dabc 716I<really> don't want to happen ever.
a0d0e21e 717
9b6570b4 718=item 4.
a0d0e21e 719
d1b91892 720The C<POPi> macro is used here to pop the return value from the stack.
721In this case we wanted an integer, so C<POPi> was used.
a0d0e21e 722
723
d1b91892 724Here is the complete list of POP macros available, along with the types
725they return.
a0d0e21e 726
d1b91892 727 POPs SV
728 POPp pointer
729 POPn double
730 POPi integer
731 POPl long
a0d0e21e 732
9b6570b4 733=item 5.
a0d0e21e 734
d1b91892 735The final C<PUTBACK> is used to leave the Perl stack in a consistent
736state before exiting the function. This is necessary because when we
737popped the return value from the stack with C<POPi> it updated only our
738local copy of the stack pointer. Remember, C<PUTBACK> sets the global
739stack pointer to be the same as our local copy.
a0d0e21e 740
741=back
742
743
d1b91892 744=head2 Returning a list of values
a0d0e21e 745
d1b91892 746Now, let's extend the previous example to return both the sum of the
747parameters and the difference.
a0d0e21e 748
d1b91892 749Here is the Perl subroutine
a0d0e21e 750
84f709e7 751 sub AddSubtract
752 {
753 my($a, $b) = @_ ;
754 ($a+$b, $a-$b) ;
a0d0e21e 755 }
756
a0d0e21e 757and 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
924508f0 770 PUSHMARK(SP) ;
a0d0e21e 771 XPUSHs(sv_2mortal(newSViv(a)));
772 XPUSHs(sv_2mortal(newSViv(b)));
773 PUTBACK ;
774
4929bf7b 775 count = call_pv("AddSubtract", G_ARRAY);
a0d0e21e 776
777 SPAGAIN ;
778
d1b91892 779 if (count != 2)
780 croak("Big trouble\n") ;
a0d0e21e 781
d1b91892 782 printf ("%d - %d = %d\n", a, b, POPi) ;
783 printf ("%d + %d = %d\n", a, b, POPi) ;
a0d0e21e 784
785 PUTBACK ;
786 FREETMPS ;
787 LEAVE ;
788 }
789
d1b91892 790If I<call_AddSubtract> is called like this
791
792 call_AddSubtract(7, 4) ;
793
794then here is the output
795
796 7 - 4 = 3
797 7 + 4 = 11
a0d0e21e 798
799Notes
800
801=over 5
802
803=item 1.
804
90fdbbb7 805We wanted list context, so G_ARRAY was used.
a0d0e21e 806
807=item 2.
808
d1b91892 809Not surprisingly C<POPi> is used twice this time because we were
810retrieving 2 values from the stack. The important thing to note is that
811when using the C<POP*> macros they come off the stack in I<reverse>
812order.
a0d0e21e 813
814=back
815
d1b91892 816=head2 Returning a list in a scalar context
817
818Say the Perl subroutine in the previous section was called in a scalar
819context, 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
924508f0 833 PUSHMARK(SP) ;
d1b91892 834 XPUSHs(sv_2mortal(newSViv(a)));
835 XPUSHs(sv_2mortal(newSViv(b)));
836 PUTBACK ;
837
4929bf7b 838 count = call_pv("AddSubtract", G_SCALAR);
d1b91892 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
852The other modification made is that I<call_AddSubScalar> will print the
853number of items returned from the Perl subroutine and their value (for
854simplicity it assumes that they are integer). So if
855I<call_AddSubScalar> is called
856
857 call_AddSubScalar(7, 4) ;
858
859then the output will be
860
861 Items Returned = 1
862 Value 1 = 3
863
864In this case the main point to note is that only the last item in the
54310121 865list is returned from the subroutine, I<AddSubtract> actually made it back to
d1b91892 866I<call_AddSubScalar>.
867
868
869=head2 Returning Data from Perl via the parameter list
a0d0e21e 870
871It is also possible to return values directly via the parameter list -
872whether it is actually desirable to do it is another matter entirely.
873
d1b91892 874The Perl subroutine, I<Inc>, below takes 2 parameters and increments
875each directly.
a0d0e21e 876
84f709e7 877 sub Inc
878 {
879 ++ $_[0] ;
880 ++ $_[1] ;
a0d0e21e 881 }
882
883and 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
924508f0 901 PUSHMARK(SP) ;
a0d0e21e 902 XPUSHs(sva);
903 XPUSHs(svb);
904 PUTBACK ;
905
4929bf7b 906 count = call_pv("Inc", G_DISCARD);
a0d0e21e 907
908 if (count != 0)
d1b91892 909 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
910 count) ;
a0d0e21e 911
912 printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
913 printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
914
915 FREETMPS ;
d1b91892 916 LEAVE ;
a0d0e21e 917 }
918
d1b91892 919To be able to access the two parameters that were pushed onto the stack
4929bf7b 920after they return from I<call_pv> it is necessary to make a note
19799a22 921of their addresses--thus the two variables C<sva> and C<svb>.
a0d0e21e 922
d1b91892 923The reason this is necessary is that the area of the Perl stack which
924held them will very likely have been overwritten by something else by
4929bf7b 925the time control returns from I<call_pv>.
a0d0e21e 926
927
928
929
d1b91892 930=head2 Using G_EVAL
a0d0e21e 931
d1b91892 932Now an example using G_EVAL. Below is a Perl subroutine which computes
933the difference of its 2 parameters. If this would result in a negative
934result, the subroutine calls I<die>.
a0d0e21e 935
84f709e7 936 sub Subtract
937 {
938 my ($a, $b) = @_ ;
a0d0e21e 939
84f709e7 940 die "death can be fatal\n" if $a < $b ;
a0d0e21e 941
84f709e7 942 $a - $b ;
a0d0e21e 943 }
944
945and 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 ;
a0d0e21e 954
955 ENTER ;
956 SAVETMPS;
957
924508f0 958 PUSHMARK(SP) ;
a0d0e21e 959 XPUSHs(sv_2mortal(newSViv(a)));
960 XPUSHs(sv_2mortal(newSViv(b)));
961 PUTBACK ;
962
4929bf7b 963 count = call_pv("Subtract", G_EVAL|G_SCALAR);
a0d0e21e 964
d1b91892 965 SPAGAIN ;
966
967 /* Check the eval first */
9cde0e7f 968 if (SvTRUE(ERRSV))
d1b91892 969 {
2d8e6c8d 970 STRLEN n_a;
971 printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
d1b91892 972 POPs ;
973 }
974 else
975 {
976 if (count != 1)
977 croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
978 count) ;
a0d0e21e 979
d1b91892 980 printf ("%d - %d = %d\n", a, b, POPi) ;
981 }
a0d0e21e 982
983 PUTBACK ;
984 FREETMPS ;
985 LEAVE ;
a0d0e21e 986 }
987
988If I<call_Subtract> is called thus
989
d1b91892 990 call_Subtract(4, 5)
a0d0e21e 991
992the following will be printed
993
d1b91892 994 Uh oh - death can be fatal
a0d0e21e 995
996Notes
997
998=over 5
999
1000=item 1.
1001
d1b91892 1002We want to be able to catch the I<die> so we have used the G_EVAL
1003flag. Not specifying this flag would mean that the program would
1004terminate immediately at the I<die> statement in the subroutine
1005I<Subtract>.
a0d0e21e 1006
1007=item 2.
1008
54310121 1009The code
a0d0e21e 1010
9cde0e7f 1011 if (SvTRUE(ERRSV))
d1b91892 1012 {
2d8e6c8d 1013 STRLEN n_a;
1014 printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
d1b91892 1015 POPs ;
1016 }
a0d0e21e 1017
d1b91892 1018is the direct equivalent of this bit of Perl
a0d0e21e 1019
d1b91892 1020 print "Uh oh - $@\n" if $@ ;
a0d0e21e 1021
9cde0e7f 1022C<PL_errgv> is a perl global of type C<GV *> that points to the
1023symbol table entry containing the error. C<ERRSV> therefore
c07a80fd 1024refers to the C equivalent of C<$@>.
1025
d1b91892 1026=item 3.
a0d0e21e 1027
d1b91892 1028Note that the stack is popped using C<POPs> in the block where
9cde0e7f 1029C<SvTRUE(ERRSV)> is true. This is necessary because whenever a
4929bf7b 1030I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
5f05dabc 1031the top of the stack holds the value I<undef>. Because we want the
d1b91892 1032program to continue after detecting this error, it is essential that
1033the stack is tidied up by removing the I<undef>.
a0d0e21e 1034
1035=back
1036
1037
c07a80fd 1038=head2 Using G_KEEPERR
1039
1040Consider this rather facetious example, where we have used an XS
1041version of the call_Subtract example above inside a destructor:
1042
1043 package Foo;
84f709e7 1044 sub new { bless {}, $_[0] }
54310121 1045 sub Subtract {
84f709e7 1046 my($a,$b) = @_;
1047 die "death can be fatal" if $a < $b ;
1048 $a - $b;
c07a80fd 1049 }
84f709e7 1050 sub DESTROY { call_Subtract(5, 4); }
1051 sub foo { die "foo dies"; }
c07a80fd 1052
1053 package main;
1054 eval { Foo->new->foo };
1055 print "Saw: $@" if $@; # should be, but isn't
1056
1057This example will fail to recognize that an error occurred inside the
1058C<eval {}>. Here's why: the call_Subtract code got executed while perl
5f05dabc 1059was cleaning up temporaries when exiting the eval block, and because
4929bf7b 1060call_Subtract is implemented with I<call_pv> using the G_EVAL
c07a80fd 1061flag, it promptly reset C<$@>. This results in the failure of the
1062outermost test for C<$@>, and thereby the failure of the error trap.
1063
4929bf7b 1064Appending the G_KEEPERR flag, so that the I<call_pv> call in
c07a80fd 1065call_Subtract reads:
1066
4929bf7b 1067 count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
c07a80fd 1068
1069will preserve the error and restore reliable error handling.
1070
4929bf7b 1071=head2 Using call_sv
a0d0e21e 1072
d1b91892 1073In all the previous examples I have 'hard-wired' the name of the Perl
1074subroutine to be called from C. Most of the time though, it is more
1075convenient to be able to specify the name of the Perl subroutine from
1076within the Perl script.
a0d0e21e 1077
1078Consider the Perl code below
1079
84f709e7 1080 sub fred
1081 {
1082 print "Hello there\n" ;
d1b91892 1083 }
1084
84f709e7 1085 CallSubPV("fred") ;
d1b91892 1086
1087Here is a snippet of XSUB which defines I<CallSubPV>.
1088
1089 void
1090 CallSubPV(name)
1091 char * name
1092 CODE:
924508f0 1093 PUSHMARK(SP) ;
4929bf7b 1094 call_pv(name, G_DISCARD|G_NOARGS) ;
a0d0e21e 1095
54310121 1096That is fine as far as it goes. The thing is, the Perl subroutine
5f05dabc 1097can be specified as only a string. For Perl 4 this was adequate,
d1b91892 1098but Perl 5 allows references to subroutines and anonymous subroutines.
4929bf7b 1099This is where I<call_sv> is useful.
d1b91892 1100
1101The code below for I<CallSubSV> is identical to I<CallSubPV> except
1102that the C<name> parameter is now defined as an SV* and we use
4929bf7b 1103I<call_sv> instead of I<call_pv>.
d1b91892 1104
1105 void
1106 CallSubSV(name)
1107 SV * name
1108 CODE:
924508f0 1109 PUSHMARK(SP) ;
4929bf7b 1110 call_sv(name, G_DISCARD|G_NOARGS) ;
a0d0e21e 1111
5f05dabc 1112Because we are using an SV to call I<fred> the following can all be used
a0d0e21e 1113
84f709e7 1114 CallSubSV("fred") ;
1115 CallSubSV(\&fred) ;
1116 $ref = \&fred ;
1117 CallSubSV($ref) ;
1118 CallSubSV( sub { print "Hello there\n" } ) ;
a0d0e21e 1119
4929bf7b 1120As you can see, I<call_sv> gives you much greater flexibility in
d1b91892 1121how you can specify the Perl subroutine.
1122
1123You should note that if it is necessary to store the SV (C<name> in the
1124example above) which corresponds to the Perl subroutine so that it can
5f05dabc 1125be used later in the program, it not enough just to store a copy of the
d1b91892 1126pointer 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:
924508f0 1139 PUSHMARK(SP) ;
4929bf7b 1140 call_sv(rememberSub, G_DISCARD|G_NOARGS) ;
a0d0e21e 1141
d1b91892 1142The reason this is wrong is that by the time you come to use the
1143pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1144to the Perl subroutine that was recorded in C<SaveSub1>. This is
1145particularly true for these cases
a0d0e21e 1146
84f709e7 1147 SaveSub1(\&fred) ;
1148 CallSavedSub1() ;
a0d0e21e 1149
84f709e7 1150 SaveSub1( sub { print "Hello there\n" } ) ;
1151 CallSavedSub1() ;
a0d0e21e 1152
d1b91892 1153By the time each of the C<SaveSub1> statements above have been executed,
54310121 1154the SV*s which corresponded to the parameters will no longer exist.
d1b91892 1155Expect an error message from Perl of the form
a0d0e21e 1156
d1b91892 1157 Can't use an undefined value as a subroutine reference at ...
a0d0e21e 1158
d1b91892 1159for each of the C<CallSavedSub1> lines.
a0d0e21e 1160
54310121 1161Similarly, with this code
a0d0e21e 1162
84f709e7 1163 $ref = \&fred ;
1164 SaveSub1($ref) ;
1165 $ref = 47 ;
1166 CallSavedSub1() ;
a0d0e21e 1167
54310121 1168you can expect one of these messages (which you actually get is dependent on
1169the version of Perl you are using)
a0d0e21e 1170
d1b91892 1171 Not a CODE reference at ...
1172 Undefined subroutine &main::47 called ...
a0d0e21e 1173
19799a22 1174The variable $ref may have referred to the subroutine C<fred>
d1b91892 1175whenever the call to C<SaveSub1> was made but by the time
5f05dabc 1176C<CallSavedSub1> gets called it now holds the number C<47>. Because we
d1b91892 1177saved only a pointer to the original SV in C<SaveSub1>, any changes to
19799a22 1178$ref will be tracked by the pointer C<rememberSub>. This means that
d1b91892 1179whenever C<CallSavedSub1> gets called, it will attempt to execute the
1180code which is referenced by the SV* C<rememberSub>. In this case
1181though, it now refers to the integer C<47>, so expect Perl to complain
1182loudly.
a0d0e21e 1183
d1b91892 1184A similar but more subtle problem is illustrated with this code
a0d0e21e 1185
84f709e7 1186 $ref = \&fred ;
1187 SaveSub1($ref) ;
1188 $ref = \&joe ;
1189 CallSavedSub1() ;
a0d0e21e 1190
d1b91892 1191This time whenever C<CallSavedSub1> get called it will execute the Perl
54310121 1192subroutine C<joe> (assuming it exists) rather than C<fred> as was
d1b91892 1193originally requested in the call to C<SaveSub1>.
a0d0e21e 1194
d1b91892 1195To get around these problems it is necessary to take a full copy of the
1196SV. The code below shows C<SaveSub2> modified to do that
a0d0e21e 1197
d1b91892 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:
924508f0 1215 PUSHMARK(SP) ;
4929bf7b 1216 call_sv(keepSub, G_DISCARD|G_NOARGS) ;
d1b91892 1217
5f05dabc 1218To avoid creating a new SV every time C<SaveSub2> is called,
d1b91892 1219the function first checks to see if it has been called before. If not,
1220then space for a new SV is allocated and the reference to the Perl
1221subroutine, C<name> is copied to the variable C<keepSub> in one
1222operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called
1223the existing SV, C<keepSub>, is overwritten with the new value using
1224C<SvSetSV>.
1225
4929bf7b 1226=head2 Using call_argv
d1b91892 1227
1228Here is a Perl subroutine which prints whatever parameters are passed
1229to it.
1230
84f709e7 1231 sub PrintList
1232 {
1233 my(@list) = @_ ;
d1b91892 1234
84f709e7 1235 foreach (@list) { print "$_\n" }
d1b91892 1236 }
1237
4929bf7b 1238and here is an example of I<call_argv> which will call
d1b91892 1239I<PrintList>.
1240
1241 static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ;
1242
1243 static void
1244 call_PrintList()
1245 {
1246 dSP ;
1247
4929bf7b 1248 call_argv("PrintList", G_DISCARD, words) ;
d1b91892 1249 }
1250
1251Note that it is not necessary to call C<PUSHMARK> in this instance.
4929bf7b 1252This is because I<call_argv> will do it for you.
d1b91892 1253
4929bf7b 1254=head2 Using call_method
a0d0e21e 1255
1256Consider the following Perl code
1257
d1b91892 1258 {
84f709e7 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 }
d1b91892 1278 }
1279
5f05dabc 1280It implements just a very simple class to manage an array. Apart from
d1b91892 1281the constructor, C<new>, it declares methods, one static and one
5f05dabc 1282virtual. The static method, C<PrintID>, prints out simply the class
d1b91892 1283name and a version number. The virtual method, C<Display>, prints out a
1284single element of the array. Here is an all Perl example of using it.
1285
84f709e7 1286 $a = new Mine ('red', 'green', 'blue') ;
1287 $a->Display(1) ;
1288 PrintID Mine;
a0d0e21e 1289
d1b91892 1290will print
a0d0e21e 1291
d1b91892 1292 1: green
54310121 1293 This is Class Mine version 1.0
a0d0e21e 1294
d1b91892 1295Calling a Perl method from C is fairly straightforward. The following
1296things are required
a0d0e21e 1297
d1b91892 1298=over 5
1299
1300=item *
1301
1302a reference to the object for a virtual method or the name of the class
1303for a static method.
1304
1305=item *
1306
1307the name of the method.
1308
1309=item *
1310
1311any other parameters specific to the method.
1312
1313=back
1314
1315Here is a simple XSUB which illustrates the mechanics of calling both
1316the 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:
924508f0 1324 PUSHMARK(SP);
d1b91892 1325 XPUSHs(ref);
1326 XPUSHs(sv_2mortal(newSViv(index))) ;
1327 PUTBACK;
1328
4929bf7b 1329 call_method(method, G_DISCARD) ;
d1b91892 1330
1331 void
1332 call_PrintID(class, method)
1333 char * class
1334 char * method
1335 CODE:
924508f0 1336 PUSHMARK(SP);
d1b91892 1337 XPUSHs(sv_2mortal(newSVpv(class, 0))) ;
1338 PUTBACK;
1339
4929bf7b 1340 call_method(method, G_DISCARD) ;
d1b91892 1341
1342
1343So the methods C<PrintID> and C<Display> can be invoked like this
1344
84f709e7 1345 $a = new Mine ('red', 'green', 'blue') ;
1346 call_Method($a, 'Display', 1) ;
1347 call_PrintID('Mine', 'PrintID') ;
d1b91892 1348
1349The only thing to note is that in both the static and virtual methods,
19799a22 1350the method name is not passed via the stack--it is used as the first
4929bf7b 1351parameter to I<call_method>.
d1b91892 1352
54310121 1353=head2 Using GIMME_V
d1b91892 1354
54310121 1355Here is a trivial XSUB which prints the context in which it is
d1b91892 1356currently executing.
1357
1358 void
1359 PrintContext()
1360 CODE:
54310121 1361 I32 gimme = GIMME_V;
1362 if (gimme == G_VOID)
1363 printf ("Context is Void\n") ;
1364 else if (gimme == G_SCALAR)
d1b91892 1365 printf ("Context is Scalar\n") ;
1366 else
1367 printf ("Context is Array\n") ;
1368
1369and here is some Perl to test it
1370
54310121 1371 PrintContext ;
84f709e7 1372 $a = PrintContext ;
1373 @a = PrintContext ;
d1b91892 1374
1375The output from that will be
1376
54310121 1377 Context is Void
d1b91892 1378 Context is Scalar
1379 Context is Array
1380
1381=head2 Using Perl to dispose of temporaries
1382
1383In the examples given to date, any temporaries created in the callback
4929bf7b 1384(i.e., parameters passed on the stack to the I<call_*> function or
d1b91892 1385values returned via the stack) have been freed by one of these methods
1386
1387=over 5
1388
1389=item *
1390
4929bf7b 1391specifying the G_DISCARD flag with I<call_*>.
d1b91892 1392
1393=item *
1394
1395explicitly disposed of using the C<ENTER>/C<SAVETMPS> -
1396C<FREETMPS>/C<LEAVE> pairing.
1397
1398=back
1399
1400There is another method which can be used, namely letting Perl do it
1401for you automatically whenever it regains control after the callback
1402has terminated. This is done by simply not using the
1403
1404 ENTER ;
1405 SAVETMPS ;
1406 ...
1407 FREETMPS ;
1408 LEAVE ;
1409
1410sequence in the callback (and not, of course, specifying the G_DISCARD
1411flag).
1412
1413If you are going to use this method you have to be aware of a possible
1414memory leak which can arise under very specific circumstances. To
1415explain these circumstances you need to know a bit about the flow of
1416control between Perl and the callback routine.
1417
1418The examples given at the start of the document (an error handler and
1419an event driven program) are typical of the two main sorts of flow
1420control that you are likely to encounter with callbacks. There is a
1421very important distinction between them, so pay attention.
1422
1423In the first example, an error handler, the flow of control could be as
1424follows. You have created an interface to an external library.
1425Control can reach the external library like this
1426
1427 perl --> XSUB --> external library
1428
1429Whilst control is in the library, an error condition occurs. You have
1430previously set up a Perl callback to handle this situation, so it will
1431get executed. Once the callback has finished, control will drop back to
1432Perl again. Here is what the flow of control will be like in that
1433situation
1434
1435 perl --> XSUB --> external library
1436 ...
1437 error occurs
1438 ...
4929bf7b 1439 external library --> call_* --> perl
d1b91892 1440 |
4929bf7b 1441 perl <-- XSUB <-- external library <-- call_* <----+
d1b91892 1442
4929bf7b 1443After processing of the error using I<call_*> is completed,
d1b91892 1444control reverts back to Perl more or less immediately.
1445
1446In the diagram, the further right you go the more deeply nested the
1447scope is. It is only when control is back with perl on the extreme
1448left of the diagram that you will have dropped back to the enclosing
1449scope and any temporaries you have left hanging around will be freed.
1450
1451In the second example, an event driven program, the flow of control
1452will be more like this
1453
1454 perl --> XSUB --> event handler
1455 ...
4929bf7b 1456 event handler --> call_* --> perl
d1b91892 1457 |
4929bf7b 1458 event handler <-- call_* <----+
d1b91892 1459 ...
4929bf7b 1460 event handler --> call_* --> perl
d1b91892 1461 |
4929bf7b 1462 event handler <-- call_* <----+
d1b91892 1463 ...
4929bf7b 1464 event handler --> call_* --> perl
d1b91892 1465 |
4929bf7b 1466 event handler <-- call_* <----+
d1b91892 1467
1468In this case the flow of control can consist of only the repeated
1469sequence
1470
4929bf7b 1471 event handler --> call_* --> perl
d1b91892 1472
54310121 1473for practically the complete duration of the program. This means that
1474control may I<never> drop back to the surrounding scope in Perl at the
1475extreme left.
d1b91892 1476
1477So what is the big problem? Well, if you are expecting Perl to tidy up
1478those temporaries for you, you might be in for a long wait. For Perl
5f05dabc 1479to dispose of your temporaries, control must drop back to the
d1b91892 1480enclosing scope at some stage. In the event driven scenario that may
1481never happen. This means that as time goes on, your program will
1482create more and more temporaries, none of which will ever be freed. As
1483each of these temporaries consumes some memory your program will
19799a22 1484eventually consume all the available memory in your system--kapow!
d1b91892 1485
19799a22 1486So here is the bottom line--if you are sure that control will revert
d1b91892 1487back to the enclosing Perl scope fairly quickly after the end of your
5f05dabc 1488callback, then it isn't absolutely necessary to dispose explicitly of
d1b91892 1489any temporaries you may have created. Mind you, if you are at all
1490uncertain 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
1496Potentially one of the trickiest problems to overcome when designing a
1497callback interface can be figuring out how to store the mapping between
1498the C callback function and the Perl equivalent.
1499
1500To help understand why this can be a real problem first consider how a
1501callback is set up in an all C environment. Typically a C API will
1502provide a function to register a callback. This will expect a pointer
1503to a function as one of its parameters. Below is a call to a
1504hypothetical function C<register_fatal> which registers the C function
1505to get called when a fatal error occurs.
1506
1507 register_fatal(cb1) ;
1508
1509The single parameter C<cb1> is a pointer to a function, so you must
1510have 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
1519Now 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
924508f0 1528 PUSHMARK(SP) ;
d1b91892 1529
1530 /* Call the Perl sub to process the callback */
4929bf7b 1531 call_sv(callback, G_DISCARD) ;
d1b91892 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
1548where the Perl equivalent of C<register_fatal> and the callback it
1549registers, C<pcb1>, might look like this
1550
1551 # Register the sub pcb1
1552 register_fatal(\&pcb1) ;
1553
84f709e7 1554 sub pcb1
1555 {
1556 die "I'm dying...\n" ;
d1b91892 1557 }
1558
1559The mapping between the C callback and the Perl equivalent is stored in
1560the global variable C<callback>.
1561
5f05dabc 1562This will be adequate if you ever need to have only one callback
d1b91892 1563registered at any time. An example could be an error handler like the
1564code sketched out above. Remember though, repeated calls to
1565C<register_fatal> will replace the previously registered callback
1566function with the new one.
1567
1568Say for example you want to interface to a library which allows asynchronous
1569file i/o. In this case you may be able to register a callback whenever
1570a read operation has completed. To be of any use we want to be able to
1571call separate Perl subroutines for each file that is opened. As it
1572stands, the error handler example above would not be adequate as it
1573allows only a single callback to be defined at any time. What we
1574require is a means of storing the mapping between the opened file and
1575the Perl subroutine we want to be called for that file.
1576
1577Say the i/o library has a function C<asynch_read> which associates a C
19799a22 1578function C<ProcessRead> with a file handle C<fh>--this assumes that it
d1b91892 1579has also provided some routine to open the file and so obtain the file
1580handle.
1581
1582 asynch_read(fh, ProcessRead)
1583
1584This may expect the C I<ProcessRead> function of this form
1585
1586 void
1587 ProcessRead(fh, buffer)
1588 int fh ;
1589 char * buffer ;
1590 {
54310121 1591 ...
d1b91892 1592 }
1593
1594To provide a Perl interface to this library we need to be able to map
1595between the C<fh> parameter and the Perl subroutine we want called. A
1596hash is a convenient mechanism for storing this mapping. The code
1597below shows a possible implementation
1598
1599 static HV * Mapping = (HV*)NULL ;
a0d0e21e 1600
d1b91892 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
1616and 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
924508f0 1631 PUSHMARK(SP) ;
d1b91892 1632 XPUSHs(sv_2mortal(newSViv(fh))) ;
1633 XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1634 PUTBACK ;
1635
1636 /* Call the Perl sub */
4929bf7b 1637 call_sv(*sv, G_DISCARD) ;
d1b91892 1638 }
1639
1640For completeness, here is C<asynch_close>. This shows how to remove
1641the 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) ;
a0d0e21e 1649
d1b91892 1650 /* Now call the real asynch_close */
1651 asynch_close(fh) ;
a0d0e21e 1652
d1b91892 1653So the Perl interface would look like this
1654
84f709e7 1655 sub callback1
1656 {
1657 my($handle, $buffer) = @_ ;
d1b91892 1658 }
a0d0e21e 1659
d1b91892 1660 # Register the Perl callback
84f709e7 1661 asynch_read($fh, \&callback1) ;
a0d0e21e 1662
84f709e7 1663 asynch_close($fh) ;
d1b91892 1664
1665The mapping between the C callback and Perl is stored in the global
1666hash C<Mapping> this time. Using a hash has the distinct advantage that
1667it allows an unlimited number of callbacks to be registered.
1668
1669What if the interface provided by the C callback doesn't contain a
1670parameter which allows the file handle to Perl subroutine mapping? Say
1671in the asynchronous i/o package, the callback function gets passed only
1672the C<buffer> parameter like this
1673
1674 void
1675 ProcessRead(buffer)
1676 char * buffer ;
1677 {
1678 ...
1679 }
a0d0e21e 1680
d1b91892 1681Without the file handle there is no straightforward way to map from the
1682C callback to the Perl subroutine.
a0d0e21e 1683
54310121 1684In this case a possible way around this problem is to predefine a
d1b91892 1685series 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
924508f0 1715 PUSHMARK(SP) ;
d1b91892 1716 XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1717 PUTBACK ;
1718
1719 /* Call the Perl sub */
4929bf7b 1720 call_sv(Map[index].PerlSub, G_DISCARD) ;
d1b91892 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
5f05dabc 1799In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to
d1b91892 1800remember the Perl subroutine to be called. Each of the functions holds
4a6725af 1801a separate hard-wired index which is used in the function C<Pcb> to
d1b91892 1802access the C<Map> array and actually call the Perl subroutine.
1803
1804There are some obvious disadvantages with this technique.
1805
1806Firstly, the code is considerably more complex than with the previous
1807example.
1808
4a6725af 1809Secondly, there is a hard-wired limit (in this case 3) to the number of
d1b91892 1810callbacks that can exist simultaneously. The only way to increase the
1811limit is by modifying the code to add more functions and then
54310121 1812recompiling. None the less, as long as the number of functions is
d1b91892 1813chosen with some care, it is still a workable solution and in some
1814cases is the only one available.
1815
1816To summarize, here are a number of possible methods for you to consider
1817for 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
1823For a lot of situations, like interfacing to an error handler, this may
1824be a perfectly adequate solution.
1825
1826=item 2. Create a sequence of callbacks - hard wired limit
1827
1828If it is impossible to tell from the parameters passed back from the C
1829callback what the context is, then you may need to create a sequence of C
1830callback interface functions, and store pointers to each in an array.
1831
1832=item 3. Use a parameter to map to the Perl callback
1833
1834A hash is an ideal mechanism to store the mapping between C and Perl.
1835
1836=back
a0d0e21e 1837
a0d0e21e 1838
1839=head2 Alternate Stack Manipulation
1840
a0d0e21e 1841
d1b91892 1842Although I have made use of only the C<POP*> macros to access values
1843returned from Perl subroutines, it is also possible to bypass these
8e07c86e 1844macros and read the stack using the C<ST> macro (See L<perlxs> for a
d1b91892 1845full description of the C<ST> macro).
1846
1847Most of the time the C<POP*> macros should be adequate, the main
1848problem with them is that they force you to process the returned values
1849in sequence. This may not be the most suitable way to process the
1850values in some cases. What we want is to be able to access the stack in
1851a random order. The C<ST> macro as used when coding an XSUB is ideal
1852for this purpose.
1853
1854The code below is the example given in the section I<Returning a list
1855of 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
924508f0 1869 PUSHMARK(SP) ;
d1b91892 1870 XPUSHs(sv_2mortal(newSViv(a)));
1871 XPUSHs(sv_2mortal(newSViv(b)));
1872 PUTBACK ;
1873
4929bf7b 1874 count = call_pv("AddSubtract", G_ARRAY);
d1b91892 1875
1876 SPAGAIN ;
924508f0 1877 SP -= count ;
9cde0e7f 1878 ax = (SP - PL_stack_base) + 1 ;
d1b91892 1879
1880 if (count != 2)
1881 croak("Big trouble\n") ;
a0d0e21e 1882
d1b91892 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
1891Notes
1892
1893=over 5
1894
1895=item 1.
1896
1897Notice that it was necessary to define the variable C<ax>. This is
1898because the C<ST> macro expects it to exist. If we were in an XSUB it
1899would not be necessary to define C<ax> as it is already defined for
1900you.
1901
1902=item 2.
1903
1904The code
1905
1906 SPAGAIN ;
924508f0 1907 SP -= count ;
9cde0e7f 1908 ax = (SP - PL_stack_base) + 1 ;
d1b91892 1909
1910sets the stack up so that we can use the C<ST> macro.
1911
1912=item 3.
1913
1914Unlike the original coding of this example, the returned
1915values are not accessed in reverse order. So C<ST(0)> refers to the
54310121 1916first value returned by the Perl subroutine and C<ST(count-1)>
d1b91892 1917refers to the last.
1918
1919=back
a0d0e21e 1920
8f183262 1921=head2 Creating and calling an anonymous subroutine in C
1922
4929bf7b 1923As we've already shown, C<call_sv> can be used to invoke an
c2611fb3 1924anonymous subroutine. However, our example showed a Perl script
1925invoking an XSUB to perform this operation. Let's see how it can be
8f183262 1926done inside our C code:
1927
8f183262 1928 ...
1929
4929bf7b 1930 SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);
8f183262 1931
1932 ...
1933
4929bf7b 1934 call_sv(cvrv, G_VOID|G_NOARGS);
8f183262 1935
4929bf7b 1936C<eval_pv> is used to compile the anonymous subroutine, which
1937will be the return value as well (read more about C<eval_pv> in
4a4eefd0 1938L<perlapi/eval_pv>). Once this code reference is in hand, it
8f183262 1939can be mixed in with all the previous examples we've shown.
1940
a0d0e21e 1941=head1 SEE ALSO
1942
8e07c86e 1943L<perlxs>, L<perlguts>, L<perlembed>
a0d0e21e 1944
1945=head1 AUTHOR
1946
0536e0eb 1947Paul Marquess
a0d0e21e 1948
d1b91892 1949Special thanks to the following people who assisted in the creation of
1950the document.
a0d0e21e 1951
c07a80fd 1952Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
1953and Larry Wall.
a0d0e21e 1954
1955=head1 DATE
1956
137443ea 1957Version 1.3, 14th Apr 1997