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