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